API Overview

Todoist API (also known as the “Sync API”) is specially designed for efficient data sync between clients (e.g. our mobile apps) and Todoist.

All Sync API requests share the same endpoint URL: https://todoist.com/API/v7/sync

Sync API requests should be made in HTTP POST (application/x-www-form-urlencoded). Sync API responses, including errors, will be returned in JSON.

Sync API supports the following features -

  • Batching: reading and writing of multiple resources can be done in a single HTTP request. Batch requests help clients reduce the number of network calls needed to sync resources.

  • Incremental sync: You only retrieve data that are updated since the last time you performed a sync request.

Note that documentation for the older Todoist API v6 is still available, but we strongly recommend you use or migrate your code to the current version, as the v6 may be deprecated in the near future.

Read resources

An example response of a read request.

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d sync_token='*' \
    -d resource_types='["all"]'

{
  "collaborators": [ ... ],
  "collaborator_states": [ ... ],
  "day_orders": { ... },
  "day_orders_timestamp": "1344642991.1",
  "filters": [ ... ],
  "full_sync" : true,
  "items": [ ... ],
  "labels": [ ... ],
  "live_notifications": [ ... ],
  "live_notifications_last_read_id": 0,
  "notes": [ ... ],
  "project_notes": [ ... ],
  "projects": [ ... ],
  "reminders": [ ... ],
  'settings_notifications: { ... },
  "sync_token": "JLlaPv840mDQK4PLl6-hmjYMbP2h_RHsfPmIXuqmJI_zRiQHFww9olfDvSSpw74nrdvS",
  "temp_id_mapping": { ... },
  "user": { ... }
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.sync()
{
  'collaborators': [ ... ],
  'collaborator_states': [ ... ],
  'day_orders': { ... },
  'day_orders_timestamp': '1344642991.1',
  'filters': [ ... ],
  'full_sync' : True,
  'items': [ ... ],
  'labels': [ ... ],
  'live_notifications': [ ... ],
  'live_notifications_last_read_id': 0,
  'notes': [ ... ],
  'project_notes': [ ... ],
  'projects': [ ... ],
  'reminders': [ ... ],
  'settings_notifications: { ... },
  'sync_token': 'JLlaPv840mDQK4PLl6-hmjYMbP2h_RHsfPmIXuqmJI_zRiQHFww9olfDvSSpw74nrdvS',
  'temp_id_mapping': { ... },
  'user': { ... }
}

Note that the following parameters mostly make sense when sending commands in the shell with curl, and not with the Python library, as many things are automated there. For example by default the Python library fetches all resource types and then always does incremental syncs, so there’s no need to specify most of the following parameters.

To retrieve your user resources, make a Sync API request with the following parameters:

Required parameters

Parameter Description
token String User’s API token
sync_token String A special string, used to allow the client to perform incremental sync. Pass * to retrieve all active resource data. More details about this below.
resource_types JSON array of strings Used to specify what resources to fetch from the server. It should be a JSON-encoded array of strings. Here is a list of avaialbe resource types: labels, projects,items, notes, filters, reminders, locations, user, live_notifications, collaborators, notification_settings. You may use all to include all the resource types.

Optional parameters

Parameter Description
day_orders_timestamp The Sync API requests return day_orders_timestamp that specifies when the day orders were last updated. If you omit day_orders_timestamp then none of them will be fetched. If you specify day_orders_timestamp then day orders will be returned if your timestamp is different from the servers. If you send day_orders_timestamp and the day orders have not been updated then the server won’t return the day_orders entry at all.

Incremental sync

Note that the Python library always does incremental syncs under the hood, so there’s no reason to worry about them if you use it.

The Sync API allows clients to retrieve only updated resources, and this is done by using the “synchronization token”, sync_token, in your Sync API request.

On your initial sync request, specify sync_token=* in your request, and all the user’s active resource data will be returned. Todoist API server will also return a new sync_token in the Sync API response.

In your subsequent Sync request, use the sync_token that you received from your previous sync response, and the Todoist API server will return only the updated resource data.

Response

When the request succeeds, an HTTP 200 response will be returned with a JSON object containing the requested resources and also a new sync_token.

Field Description
sync_token A new synchronization token. Used by the client in the next sync request to perform an incremental sync.
full_sync Whether the response contains all data (a full synchronization) or just a part of them since the last sync.
user A user object.
projects An array of project objects.
items A array of item objects.
labels An array of label objects.
filters A array of filter objects.
day_orders A JSON object specifying the order of items in daily agenda. If day_orders_timestamp is sent and day orders have not been updated then day_orders won’t be returned at all!
day_orders_timestamp A string specifying when day orders were last updated. Use this to not fetch day orders on every request.
reminders An array of reminder objects.
collaborators A JSON object containing all collaborators for all shared projects. The projects field contains the list of all shared projects, where the user acts as one of collaborators.
collaborators_states An array specifying the state of each collaborator in each project. The state can be invited, active, inactive, deleted.
live_notifications An array of live_notification objects
live_notifications_last_read What is the last live notification the user has seen? This is used to implement unread notifications.
settings_notifications User’s notification setting, used by clients that support native notifications.

Write resources

Example API call that creates a new project.

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "project_add", "temp_id": "381e601f-0ef3-4ed6-bf95-58f896d1a314", "uuid": "ed1ce597-e4c7-4a88-ba48-e048d827c067", "args": {"name": "Project1", "item_order": 1, "indent": 1, "color": 1}}]'
{
  "sync_token": "JLlaPv840mDQK4PLl6-hmjYMbP2h_RHsfPmIXuqmJI_zRiQHFww9olfDvSSpw74nrdvS",
  "sync_status": {"ed1ce597-e4c7-4a88-ba48-e048d827c067": "ok"},
  "temp_id_mapping": {"381e601f-0ef3-4ed6-bf95-58f896d1a314": 128501470}
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.sync(commands=[{'type': 'project_add', 'temp_id': '381e601f-0ef3-4ed6-bf95-58f896d1a314', 'uuid': 'ed1ce597-e4c7-4a88-ba48-e048d827c067', 'args': {'name': 'Project1', 'item_order': 1, 'indent': 1, 'color': 1}}]
{
  'sync_status': {'ed1ce597-e4c7-4a88-ba48-e048d827c067': 'ok'},
  'temp_id_mapping': {'381e601f-0ef3-4ed6-bf95-58f896d1a314': 128501470},
  'sync_token': 'JLlaPv840mDQK4PLl6-hmjYMbP2h_RHsfPmIXuqmJI_zRiQHFww9olfDvSSpw74nrdvS'
}

Note that the Python example is only there to show what is the equivalent for sending commands, but actually there’s no need to use that with the Python library, as it has its own object oriented API which is a lot easier to do various things, so many of the parameters mentioned below do not make much sense for the Python library, and instead you can just use the methods described in the following sections.

To write to your user’s Todoist resources, make a Sync API request with the following parameters

Required parameters

Parameter Description
commands A JSON array of Command object. Each command will be processed in the specified order.
token API token

Command object

Field Description
type String The type of the command.
args Object The arguments of this specific command.
uuid String Command UUID. More details about this below.
temp_id String Temporary resource ID, Optional. Only specified for commands that create new resource (“item_add” command). More details about this below.

Command UUID

Note that the Python library takes care of sending UUIDs, so there’s no need to worry about them if you use it.

API clients should generate a unique string ID for each command and specify it in the uuid field. The Command UUID will be used for two purposes:

  1. Command result mapping: Each command’s result will be stored in the sync_status field of the response JSON object. The sync_status object has its key mapped to a command’s uuid and its value containing the result of a command.

  2. Command idempotency: Todoist will not execute command that has same UUID as the previously executed commands. This will allow clients to safely retry each command without accidentally performing the command twice.

Temporary resource id

An example that shows how temporary ids can be used and referenced:

[
  { "type": "project_add",
    "temp_id": "c7beb07f-b226-4eb1-bf63-30d782b07b1a",
    "args": {
      "name": "Test Project"
    },
    "uuid": "ac417051-1cdc-4dc3-b4f8-14526d5bfd16"
  },
  {
    "type": "item_add",
    "temp_id": "43f7ed23-a038-46b5-b2c9-4abda9097ffa",
    "args": {
      "content": "This is a test task",
      "project_id": "c7beb07f-b226-4eb1-bf63-30d782b07b1a"
    },
    "uuid": "849fff4e-8551-4abb-bd2a-838d092775d7"
  }
]

You can see that the project_add command specified a temp_id property (“c7beb07f-b226-4eb1-bf63-30d782b07b1a”) as placeholder of the actual project_id. The item_add command can refrence to this temporary project id. The API will automatically resolve these ids. “`

Note that the Python library takes care of handling temporary ids, so there’s no reason to worry about them if you use it.

Some commands depend on the result of previous command. For instance, you have a command sequence: "project_add" and "item_add" which first creates a project and then add a new task to the newly created project. In order to run the later item_add command, we need to obtain the project ID returned from the previous command. Therefore, the normal approach would be to run these two commands in two separate HTTP requests.

The temporary resource ID feature allows you to run two or more dependent commands in a single HTTP request. For commands that are related to creation of resources (i.e. item_add, project_add), you can specify an extra temp_id as a placeholder for the actual ID of the resource. The other commands in the same sequence could directly refer to temp_id if needed.

Response / Error

The result of command executions will be stored in the following response JSON object field:

Data Description
temp_id_mapping Object A dictionary object that maps temporary resource ids to real resource ids.
sync_status Object A dictionary object containing result of each command execution. The key will be the command’s uuid field and the value will be the result status of the command execution.

An example of a single request sync return value:

{
  "sync_status": {"863aca2c-65b4-480a-90ae-af160129abbd": "ok"}
}

An example of a multiple requests sync return value:

{
  "sync_status": {
    "32eaa699-e9d7-47ed-91ea-e58d475791f1": "ok",
    "bec5b356-3cc1-462a-9887-fe145e3e1ebf": {"error_code": 15, "error": "Invalid temporary id"}
  }
}

An example of a single request operating on multiple objects return value:

{
  "sync_status": {
    "66386321-fb87-4f95-9dfe-7bf5c3823e85" : {
        "128501470": "ok",
        "128501607": {"error_code": 20, "error": "Project not found"}
    }
  }
}

The status result of each command execution is in the sync_status dictionary object. The key is a command uuid and the value will be the result status of the command execution. There are two possible values for each command status -

  • an "ok” string which signals success of the command

  • an error object containings error information of a command.

Please see the adjacent code examples for the possible format of the sync_status.

Response status codes

The server uses the HTTP status codes to indicate the success or failure of a request. And as is customary in web servers, a 2xx code indicates - success, a 4xx code - an error due to incorrect user provided information, and a 5xx code - an internal, possibly temporary, error.

Status code Description
200 OK The request was processed successfuly.
400 Bad Request The request was incorrect.
401 Unauthorized Authentication is required, and has failed, or has not yet been provided.
403 Forbidden The request was valid, but for something that is forbidden.
404 Not Found The requested resource could not be found.
429 Too Many Requests The user has sent too many requests in a given amount of time.
500 Internal Server Error The request failed due to a server error.
503 Service Unavailable The server is currently unable to handle the request.

Limits

The maximum number of commands is 100 per request, and this is done to prevent timeouts and other problems when dealing with big requests.

There’s also a maximum number of 50 sync requests per minute for each user, in order to prevent clients from accidentally overloading our servers.

Client libraries

Python

install todoist python library via pip:

$ pip install todoist-python

Github

Library doc

PyPI

v6 to v7 migration guide

The new v7 Todoist API is still based on the original Todoist Sync API (as was the case for the v6 API), so the differences between the two APIs aren’t as extended as those between the v5 and v6 APIs.

In this section we document all the changes between the two different versions of our API, in order to make it easier to upgrade your client code.

The main difference between the two APIs is that the seq_no, ie. the sequence number which was basically an always increasing number, is not used anymore to implement the incremental sync functionality, but instead the sync_token has been introduced, a string hash value. So in order to do the initial full sync instead of seq_no=0, one needs to send sync_token=*. Other than than, the last known value of sync_token should be used in order to an incremental sync, similar to what was done before with the seq_no.

Here follows a list of various minor changes from the previous API version:

  • The sync_token value is not returned by the sync call anymore, but the sync_token and the full_sync variables are returned instead.
  • The sync call now returns all objects in underscore naming convention, instead of CamelCase, so the Collaborators, CollaboratorStates, DayOrders, DayOrdersTimestamp, Filters, Items, Labels, LiveNotifications, LiveNotificationsLastRead, Notes, Projects, Reminders, SettingsNotifications, SyncStatus, TempIdMapping, and User objects, where renamed to collaborators, collaborator_states, day_orders, day_orders_timestamp, filters, items, labels, live_notifications, live_notifications_last_read, notes, projects, reminders, settings_notifications, sync_status, temp_id_mapping, and user, respectively
  • The UserId variable is not returned by the sync call anymore.
  • The timezone and tz_offset properties of the user were replaced by the tz_info object.
  • The is_dummy and guide_mode properties of the user were removed.
  • The has_push_reminders, beta, restrictions, and dateist_inline_disabled properties of the user were moved to the features object.
  • The uid property of labels was removed.
  • The user_id property of filters was removed.
  • The due_date property of reminders was removed.
  • The user_id, archived_date, and archived_timestamp properties of projects were removed.
  • The due_date property of items was removed.
  • Only 10 notes per item are returned with the sync call and thus the get_item call should be used for more.

Authorization

In order to make authorized calls to Todoist APIs, your application must first obtain an access token from the users. This section describes the different ways of obtaining such a token.

Note that we encourage your application to use the OAuth protocol to obtain the access token from the user, as the other authentication methods (login and login_with_google) are scheduled for deprecation.

OAuth

External applications could obtain a user authorized API token via the OAuth2 protocol. Before getting started, developers need to create their applications in App Management Console and configure a valid OAuth redirect URL. A registered Todoist application is assigned a unique Client ID and Client Secret which are needed for the OAuth2 flow.

This procedure is comprised of 3 steps, which will be described below.

Step 1: The authorization request

An example of redirecting a user to the authorization URL:

$ curl "https://todoist.com/oauth/authorize" \
    -d "client_id=0123456789abcdef" \
    -d "scope=data:read,data:delete" \
    -d "state=secretstring"

Redirect users to the authorization URL at the endpoint https://todoist.com/oauth/authorize, with the specified request parameters.

Here follow the required parameters:

Name Description
client_id The unique Client ID of the Todoist application that you registered.
scope A comma separated list of permissions that you would like the users to grant to your application. See below a table with more details about this.
state A unique and unguessable string. It is used to protect you against cross-site request forgery attacks.

Here are the scope parameters mentioned before:

Name Description
task:add Grants permission to add tasks to the Inbox project (the application cannot read tasks data). This is only used by the helper method of adding an item.
data:read Grants read-only access to application data, including tasks, projects, labels, and filters.
data:read_write Grants read and write access to application data, including tasks, projects, labels, and filters. This scope includes task:add and data:read scopes.
data:delete Grants permission to delete application data, including tasks, labels, and filters.
project:delete Grants permission to delete projects.

And here are some common errors that you may encounter:

Error Description
User Rejected Authorization Request When the user denies your authorization request, Todoist will redirect the user to the configured redirect URI with the error parameter: http://example.com?error=access_denied.
Redirect URI Not Configured This JSON error will be returned to the requester (your user’s browser) if redirect URI is not configured in the App Management Console.
Invalid Application Status When your application exceeds the maximum token limit or when your application is being suspended due to abuse, Todoist will redirect the user to the configured redirect URI with the error parameter: http://example.com?error=invalid_application_status.
Invalid Scope When the scope parameter is invalid, Todoist will redirect the user to the configured redirect URI with error parameter: http://example.com?error=invalid_scope.

Step 2: The redirection to your application site

When the user grants your authorization request , the user will be redirected to the redirect URL configured in your application setting. The redirect request will come with two query parameters attached: code and state.

The code parameter contains the authorization code that you will use to exchange for an access token. The state parameter should match the state parameter that you supplied in the previous step. If the state is unmatched, your request has been compromised by other parties, and the process should be aborted.

Step 3: The token exchange

An example of exchanging the token:

$ curl "https://todoist.com/oauth/access_token" \
    -d "client_id=0123456789abcdef" \
    -d "client_secret=secret" \
    -d "code=abcdef" \
    -d "redirect_uri=https://example.com"

On success, Todoist returns HTTP 200 with token in JSON object format:

{
  "access_token": "0123456789abcdef0123456789abcdef01234567",
  "token_type": "Bearer"
}

Once you have the authorization code, you can exchange it for the access token at the endpoint POST https://todoist.com/oauth/access_token.

Here follow the required parameters:

Name Description
client_id The unique Client ID of the Todoist application that you registered.
client_secret The unique Client Secret of the Todoist application that you registered.
code The unique string code that you obtained in the previous step.

And here are some common errors that you may encounter (all the error responses will be in JSON format):

Error Description
Bad Authorization Code Error Occurs when the code parameter does not match the code that is given in the redirect request: {"error": "bad_authorization_code"}
Incorrect Client Credentials Error Occurs when the client_id or client_secret parameters are incorrect: {"error": "incorrect_application_credentials"}

Revoke Access Tokens

Access tokens obtained via OAuth could be revoked making a JSON request (HTTP POST) to the following endpoint: https://todoist.com/api/access_tokens/revoke

curl https://todoist.com/api/access_tokens/revoke -H "Content-Type: application/json" -X POST -d '{"client_id":"xyz", "client_secret":"xyz", "access_token":"xyz"}'

Required parameters:

Name Description
client_id The unique Client ID of the Todoist application that you registered.
client_secret The unique Client Secret of the Todoist application that you registered.
access_token Access token obtained from the OAuth authentication

Upon successful request, a HTTP 204 response will be returned.

Migrate Personal Tokens to OAuth Tokens

Tokens obtained via the old email/password authentication method could be migrated to the new OAuth access token. Migrating your users' personal tokens will allow users to see your app in their Todoist Setting page and give them the ability to manage their app authorization.

Migration API endpoint (HTTP POST, with JSON request parameters): https://todoist.com/api/access_tokens/migrate_personal_token

curl https://todoist.com/api/access_tokens/migrate_personal_token -H "Content-Type: application/json" -X POST -d '{"client_id":"xyz", "client_secret":"xyz", "personal_token":"xyz", "scope": "data:read"}'

{"access_token": "....", "token_type": "Bearer"}

Required parameters:

Name Description
client_id The unique Client ID of the Todoist application that you registered.
client_secret The unique Client Secret of the Todoist application that you registered.
personal_token Token obtained from the email/password authentication
scope Scopes of the OAuth token. Please refer to the OAuth section for the detailed list of available scopes.

Upon succesful request, a HTTP 200 response will be returned with a new OAuth token in JSON format: {"access_token": "....", "token_type": "Bearer"}

Cross Origin Resource Sharing

All API endpoints support Cross Origin Resource Sharing (CORS) for requests from any origin. The header Access-Control-Allow-Origin: * is set for successfully authenticated requests.

CORS headers example:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -H 'Origin: http://example.com'
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
>>> import requests
>>> requests.post('https://todoist.com/API/v7/sync',
...               data={'token': '0123456789abcdef0123456789abcdef01234567'},
...               headers={'Origin': 'https://example.com'}).headers

{'Access-Control-Allow-Credentials': 'false', 'Access-Control-Allow-Origin': '*', <...>}

Projects

An example project object

{
  "id": 128501470,
  "name": "Project1",
  "color": 1,
  "indent": 1,
  "item_order": 36,
  "collapsed": 0,
  "shared": false,
  "is_deleted": 0,
  "is_archived": 0,
}

Properties

Property Description
id Integer The id of the project.
name String The name of the project.
color Integer The color of the project (a number between 0 and 11, or between 0 and 21 for premium users). The color codes corresponding to these numbers are: #95ef63, #ff8581, #ffc471, #f9ec75, #a8c8e4, #d2b8a3, #e2a8e4, #cccccc, #fb886e, #ffcc00, #74e8d3, #3bd5fb. And for the additional colors of the premium users: #dc4fad, #ac193d, #d24726, #82ba00, #03b3b2, #008299, #5db2ff, #0072c6, #000000, #777777.
indent Integer The indent of the item (a number between 1 and 4, where 1 is top-level).
item_order Integer Project’s order in the project list (a number, where the smallest value should place the project at the top).
collapsed Integer Whether the project’s sub-projects are collapsed (where 1 is true and 0 is false).
shared Boolean Whether the project is shared (a true or false value).
is_deleted Integer Whether the project is marked as deleted (where 1 is true and 0 is false).
is_archived Integer Whether the project is marked as archived (where 1 is true and 0 is false).
inbox_project Boolean Whether the project is Inbox (true or otherwise this property is not sent).
team_inbox Boolean Whether the project is TeamInbox (true or otherwise this property is not sent).

Add a project

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "project_add", "temp_id": "4ff1e388-5ca6-453a-b0e8-662ebf373b6b", "uuid": "32774db9-a1da-4550-8d9d-910372124fa4", "args": {"name": "Project4"}}]'
{ ...
  "sync_status": {"32774db9-a1da-4550-8d9d-910372124fa4": "ok"},
  "temp_id_mapping": {"4ff1e388-5ca6-453a-b0e8-662ebf373b6b": 128501815},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> project = api.projects.add('Project4')
>>> api.commit()

Add a new project.

Required arguments

Argument Description
name String The name of the project (a string value).

Optional arguments

Argument Description
color Integer The color of the project (a number between 0 and 11, or between 0 and 21 for premium users).
indent Integer The indent of the item (a number between 1 and 4, where 1 is top-level).
item_order Integer Project’s order in the project list (a number, where the smallest value should place the project at the top).

Update a project

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands=[{"type": "project_update", "uuid": "1ca42128-d12f-4a66-8413-4d6ff2838fde", "args": {"id": 128501815, "indent": 2}}]'
{ ...
  "sync_status": {"1ca42128-d12f-4a66-8413-4d6ff2838fde": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> project = api.projects.get_by_id(128501815)
>>> project.update(indent=2)
>>> api.commit()

Update an existing project.

Required parameters

Argument Description
id Integer or String (temp_id) The id of the project (could be temp id).

Optional arguments

Argument Description
name String The name of the project (a string value).
color Integer The color of the project (a number between 0 and 11, or between 0 and 21 for premium users).
indent Integer The indent of the item (a number between 1 and 4, where 1 is top-level).
item_order Integer Project’s order in the project list (a number, where the smallest value should place the project at the top).
collapsed Integer Whether the project’s sub-projects are collapsed (where 1 is true and 0 is false).

Delete projects


$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands=[{"type": "project_delete", "uuid": "367182ba-125f-4dbb-bff6-c1343fd751e4", "args": {"ids": [128501815]}}]'
{ ...
  "sync_status": {"367182ba-125f-4dbb-bff6-c1343fd751e4": {"128501815": "ok"}},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> project = api.projects.get_by_id(128501815)
>>> project.delete()
>>> api.commit()

Delete an existing project.

Required arguments

Argument Description
ids Array of Integer (id) or String (temp id) List of the ids of the projects to delete (could be temp ids).

Archive a project

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands=[{"type": "project_archive", "uuid": "bbec1a60-2bdd-48ac-a623-c8eb968e1697", "args": {"ids": [128501682]}}]'
{ ...
  "sync_status": {"bbec1a60-2bdd-48ac-a623-c8eb968e1697": {"128501682": "ok"}},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> project = api.projects.get_by_id(128501682)
>>> project.archive()
>>> api.commit()

Archive project and its children. Only available for Todoist Premium users.

Required arguments

Argument Description
ids Array of Integer (id) or String (temp id) List of the ids of the projects to archive (could be temp ids).

Unarchive a project

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands=[{"type": "project_unarchive", "uuid": "7d86f042-e098-4fa6-9c1f-a61fe8c39d74", "args": {"ids": [128501682]}}]'
{ ...
  "sync_status": {"7d86f042-e098-4fa6-9c1f-a61fe8c39d74": {"128501682": "ok"}},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> project = api.projects.get_by_id(128501815)
>>> project.unarchive()
>>> api.commit()

Unarchive project and its children. Only available for Todoist Premium users.

Required arguments

Argument Description
ids Array of Integer (id) or String (temp id) List of the ids of the projects to unarchive (could be temp ids).

Update multiple orders/indents

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands=[{"type": "project_update_orders_indents", "uuid": "bf0855a3-0138-4b76-b895-88cad8db9edc", "args": {"ids_to_orders_indents": {"128501470": [42, 1], "128501607": [43, 1]}}}]'
{ ...
  "sync_status": {
    "bf0855a3-0138-4b76-b895-88cad8db9edc": {
      "128501470": "ok",
      "128501607": "ok"
    },
  },
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.projects.update_orders_indents({128501470: [42, 1], 128501607: [43, 1]})
>>> api.commit()

Update the orders and indents of multiple projects at once.

Required arguments

Argument Description
ids_to_orders_indents Object A dictionary object, with a project id as key and a two elements list as value: project_id: [item_order, indent]

Templates

Templates allow exporting of a projects tasks into a file or URL, and then importing of the complete task list to a new or existing project. Note that, templates are only available for Todoist Premium users.

Import into project

On success, an HTTP 200 OK with JSON data of file data is returned:

$ curl https://todoist.com/API/v7/templates/import_into_project \
    -F token=0123456789abcdef0123456789abcdef01234567 \
    -F project_id=128501470 \
    -F file=@example.csv
{
  "status": "ok"
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.templates.import_into_project(128501470, 'example.csv')
{
  'status': 'ok'
}

Upload a file suitable to be passed as a template to be imported into a project.

Export as file

On success, a CSV template is returned:

$ curl https://todoist.com/API/v7/templates/export_as_file \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d project_id=128501470
TYPE,CONTENT,PRIORITY,INDENT,AUTHOR,RESPONSIBLE,DATE,DATE_LANG
task,Task1,4,1,Firstname (1),,,en
,,,,,,,
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.templates.export_as_file(128501470)
TYPE,CONTENT,PRIORITY,INDENT,AUTHOR,RESPONSIBLE,DATE,DATE_LANG
task,Task1,4,1,Firstname (1),,,en
,,,,,,,

Get a template for a project as a file.

Export as shareable URL

On success, a URL is returned:

$ curl https://todoist.com/API/v7/templates/export_as_url \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d project_id=128501470
{
  "file_name": "*_Project1.csv",
  "file_url": "https://*.cloudfront.net/*_Project1.csv"
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.templates.export_as_url(128501470)
{
  'file_name': '*_Project1.csv',
  'file_url': 'https://*.cloudfront.net/*_Project1.csv'
}

Get a template for a project as a shareable URL.

The URL can then be passed to https://todoist.com/importFromTemplate?t_url=<url> to make a sharable template.

Items

An example item object

{
  "id": 33511505,
  "user_id": 1855589,
  "project_id": 128501470,
  "content": "Task1",
  "date_string": "",
  "date_lang": "en",
  "due_date_utc": null,
  "indent": 1,
  "priority": 1,
  "item_order": 1,
  "day_order": -1,
  "collapsed": 0,
  "children": null,
  "labels": [12839231, 18391839],
  "assigned_by_uid": 1855589,
  "responsible_uid": null,
  "checked": 0,
  "in_history": 0,
  "is_deleted": 0,
  "is_archived": 0,
  "sync_id": null,
  "date_added": "Fri 26 Sep 2014 08:25:05 +0000"
}

Properties

Property Description
id Integer The id of the task.
user_id Integer The owner of the task.
project_id Integer Project that the task resides in
content String The text of the task
date_string String The date of the task, added in free form text, for example it can be every day @ 10 (or null or an empty string if not set). Look at our reference to see which formats are supported.
date_lang String The language of the date_string (valid languages are: en, da, pl, zh, ko, de, pt, ja, it, fr, sv, ru, es, nl).
due_date_utc String The date of the task in the format Mon 07 Aug 2006 12:34:56 +0000 (or null if not set). For all day task (i.e. task due “Today”), the time part will be set as xx:xx:59.
priority Integer The priority of the task (a number between 1 and 4, 4 for very urgent and 1 for natural).
indent Integer The indent of the task (a number between 1 and 4, where 1 is top-level).
item_order Integer The order of the task inside a project (the smallest value would place the task at the top).
day_order Integer The order of the task inside the Today or Next 7 days view (a number, where the smallest value would place the task at the top).
collapsed Integer Whether the task’s sub-tasks are collapsed (where 1 is true and 0 is false).
labels Array of Integer The tasks labels (a list of label ids such as [2324,2525]).
assigned_by_uid Integer The id of the user who assigns the current task. This makes sense for shared projects only. Accepts 0 or any user id from the list of project collaborators. If this value is unset or invalid, it will automatically be set up to your uid.
responsible_uid Integer The id of user who is responsible for accomplishing the current task. This makes sense for shared projects only. Accepts any user id from the list of project collaborators or null or an empty string to unset.
checked Integer Whether the task is marked as completed (where 1 is true and 0 is false).
in_history Integer Whether the task has been marked as completed and is marked to be moved to history, because all the child tasks of its parent are also marked as completed (where 1 is true and 0 is false)
is_deleted Integer Whether the task is marked as deleted (where 1 is true and 0 is false).
is_archived Integer Whether the task is marked as archived (where 1 is true and 0 is false).
sync_id Integer A special id for shared tasks (a number or null if not set). Used internally and can be ignored.
date_added String The date when the task was created.

Add an item

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_add", "temp_id": "43f7ed23-a038-46b5-b2c9-4abda9097ffa", "uuid": "997d4b43-55f1-48a9-9e66-de5785dfd69b", "args": {"content": "Task1", "project_id": 128501470}}]'
{ ...
  "sync_status": {"997d4b43-55f1-48a9-9e66-de5785dfd69b": "ok"},
  "temp_id_mapping": {"43f7ed23-a038-46b5-b2c9-4abda9097ffa": 33548400},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> item = api.items.add('Task1', 128501470)
>>> api.commit()

Add a new task to a project.

Required arguments

Argument Description
content String The text of the task (a string value).

Optional arguments

Argument Description
project_id Integer or String (temp id) The id of the project to add the task to (a number or a temp id). By default the task is added to the user’s Inbox project.
date_string String The date of the task, added in free form text, for example it can be every day @ 10 (or null or an empty string to unset). Look at our reference to see which formats are supported.
date_lang String The language of the date_string (valid languages are: en, da, pl, zh, ko, de, pt, ja, it, fr, sv, ru, es, nl).
due_date_utc String The date of the task in the format YYYY-MM-DDTHH:MM (for example: 2012-3-24T23:59). The value of due_date_utc must be in UTC. Note that, when the due_date_utc argument is specified, the date_string is required and has to specified as well, and also, the date_string argument will be parsed as local timestamp, and converted to UTC internally, according to the user’s profile settings.
priority Integer The priority of the task (a number between 1 and 4, 4 for very urgent and 1 for natural).
indent Integer The indent of the task (a number between 1 and 4, where 1 is top-level).
item_order Integer The order of the task inside a project (a number, where the smallest value would place the task at the top).
day_order Integer The order of the task inside the Today or Next 7 days view (a number, where the smallest value would place the task at the top).
collapsed Integer Whether the task’s sub-tasks are collapsed (where 1 is true and 0 is false).
labels Array of Integer The tasks labels (a list of label ids such as [2324,2525]).
assigned_by_uid Integer The id of user who assigns the current task. This makes sense for shared projects only. Accepts 0 or any user id from the list of project collaborators. If this value is unset or invalid, it will be automatically setup to your uid.
responsible_uid Integer The id of user who is responsible for accomplishing the current task. This makes sense for shared projects only. Accepts any user id from the list of project collaborators or null or an empty string to unset.

Update an item

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_update", "uuid": "318d16a7-0c88-46e0-9eb5-cde6c72477c8", "args": {"id": 33548400, "priority": 2}}]'
{ ...
  "sync_status": {"318d16a7-0c88-46e0-9eb5-cde6c72477c8": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> item = api.items.get_by_id(33548400)
>>> item.update(priority=2)
>>> api.commit()

Update a task.

Required arguments

Argument Description
id Integer or String (temp id) The id of the task.

Optional arguments

Argument Description
content String The text of the task.
date_string String The date of the task, added in free form text, for example it can be every day @ 10 (or null or an empty string to unset). Look at our reference to see which formats are supported.
date_lang String The language of the date_string (valid languages are: en, da, pl, zh, ko, de, pt, ja, it, fr, sv, ru, es, nl).
due_date_utc String The date of the task in the format YYYY-MM-DDTHH:MM (for example: 2012-3-24T23:59). The value of due_date_utc must be in UTC. Note that, when the due_date_utc argument is specified, the date_string is required and has to specified as well, and also, the date_string argument will be parsed as local timestamp, and converted to UTC internally, according to the user’s profile settings.
priority Integer The priority of the task (a number between 1 and 4, 4 for very urgent and 1 for natural).
indent Integer The indent of the task (a number between 1 and 4, where 1 is top-level).
item_order Integer The order of the task inside a project (a number, where the smallest value would place the task at the top).
day_order Integer The order of the task inside the Today or Next 7 days view (a number, where the smallest value would place the task at the top).
collapsed Integer Whether the task’s sub-tasks are collapsed (where 1 is true and 0 is false).
labels Array of Integer The tasks labels (a list of label ids such as [2324,2525]).
assigned_by_uid Integer The id of the user who assigns the current task. This makes sense for shared projects only. Accepts 0 or any user id from the list of project collaborators. If this value is unset or invalid, it will be automatically setup to your uid.
responsible_uid Integer The id of user who is responsible for accomplishing the current task. This makes sense for shared projects only. Accepts any user id from the list of project collaborators or null or an empty string to unset.

Delete items

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_delete", "uuid": "f8539c77-7fd7-4846-afad-3b201f0be8a5", "args": {"ids": [33548400]}}]'
{ ...
  "sync_status": {"f8539c77-7fd7-4846-afad-3b201f0be8a5": {"33548400": "ok"}},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> item = api.items.get_by_id(33548400)
>>> item.delete()
>>> api.commit()

Delete an existing task.

Required arguments

Argument Description
ids Array of Integer (id) or String (temp id) List of the ids of the tasks to delete.

Move an item

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_move", "uuid": "818f108a-36d3-423d-857f-62837c245f3b", "args": {"project_items": {"128501470": [33548400]}, "to_project": 128501607}}]'
{ ...
  "sync_status": {"818f108a-36d3-423d-857f-62837c245f3b": {"33548400": "ok"}},
  ... }

>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.items.get_by_id(33548400)
>>> item.move(128501607)
>>> api.commit()

Move a task from one project to another project.

Required arguments

Argument Description
project_items Object A JSON mapping telling Todoist where the items are currently found. From project ids to item ids, for example {"1523":["9637423"]}, where 1523 is the project id and 9637423 is the item id.
to_project Integer The project id that the tasks should be moved to, for example 1245.

Complete items

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_complete", "uuid": "a74bfb5c-5f1d-4d14-baea-b7415446a871", "args": {"ids": [33548400]}}]'
{ ...
  "sync_status": {"a74bfb5c-5f1d-4d14-baea-b7415446a871": {"33548400": "ok"}},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.items.get_by_id(33548400)
>>> item.complete()
>>> api.commit()

Complete tasks and optionally move them to history. See also item_close for a simplified version of the command.

Required arguments

Argument Description
ids Array of Integer or String (temp id) A JSON list of ids to complete (numbers or temp ids).

Optional arguments

Argument Description
force_history Integer Whether these tasks should be moved to history (where 1 is true and 0 is false, and the default is 1) This is useful when checking off sub tasks.

Uncomplete items

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_uncomplete", "uuid": "710a60e1-174a-4313-bb9f-4df01e0349fd", "args": {"ids": [33548400]}}]'
{ ...
  "sync_status": {"710a60e1-174a-4313-bb9f-4df01e0349fd": {"33548400": "ok"}},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.items.get_by_id(33548400)
>>> item.uncomplete()
>>> api.commit()

Uncomplete tasks and move them to the active projects.

Required arguments

Argument Description
ids Array of Integer or String (temp id) A list of items to uncomplete.

Optional arguments

Argument Description
restore_state Object A dictionary object, where the item id is the key, and its value is a list of four elements, whether the item is in history, whether it is checked, its order and indent - item_id: [in_history, checked, item_order, indent]

Complete a recurring task

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_update_date_complete", "uuid": "c5888360-96b1-46be-aaac-b49b1135feab", "args": {"id": 33548400, "new_date_utc": "2014-10-30T23:59", "date_string": "every day", "is_forward": 1}}]'
{ ...
  "sync_status": {"c5888360-96b1-46be-aaac-b49b1135feab": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.items.update_date_complete(33548400, '2014-10-30T23:59', 'every day', 1)
>>> api.commit()

Complete a recurring task, and the reason why this is a special case is because we need to mark a recurring completion (and using item_update won’t do this). See also item_close for a simplified version of the command.

Required arguments

Argument Description
id Integer or String The id of the item to update (a number or a temp id).

Optional arguments

Argument Description
new_date_utc String The date of the task in the format YYYY-MM-DDTHH:MM (for example: 2012-3-24T23:59). The value of new_date_utc must be in UTC. Note that, when the new_date_utc argument is specified, the date_string is required and has to specified as well, and also, the date_string argument will be parsed as local timestamp, and converted to UTC internally, according to the user’s profile settings.
date_string String The date of the task, added in free form text, for example it can be every day @ 10 (or null or an empty string to unset). Look at our reference to see which formats are supported.
is_forward Integer Whether the task is to be completed (value 1) or uncompleted (value 0), while the default is 1.

Close item

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_close", "uuid": "c5888360-96b1-46be-aaac-b49b1135feab", "args": {"id": 33548400}}]'
{ ...
  "sync_status": {"c5888360-96b1-46be-aaac-b49b1135feab": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.items.get_by_id(33548400)
>>> item.close()
>>> api.commit()

A simplified version of item_complete / item_update_date_complete. The command does exactly what official clients do when you close a task: regular task is completed and moved to history, subtask is checked (marked as done, but not moved to history), recurring task is moved forward (due date is updated).

Required arguments

Argument Description
id Integer or String (temp id) The id of the item to close (a number or a temp id).

Update multiple orders/indents

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_update_orders_indents", "uuid": "a2bf0c06-f834-4442-99ab-b86fdfc66ed5", "args": {"ids_to_orders_indents": {"33548400": [1, 1]}}}]'
{ ...
  "sync_status": {"a2bf0c06-f834-4442-99ab-b86fdfc66ed5": {"33548400": "ok"}},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.items.update_orders_indents({33548400: [1, 1]})
>>> api.commit()

Update the orders and indents of multiple items at once.

Required arguments

Argument Description
ids_to_orders_indents Object A dictionary, where an item id is the key, and a list with two elements, the order and the indent, are its value: item_id: [item_order, indent].

Update day orders

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "item_update_day_orders", "uuid": "dbeb40fc-905f-4d8a-8bae-547d3bbd6e91", "args": {"ids_to_orders": {"33548400": 1}}}]'
{ ...
  "sync_status": {"dbeb40fc-905f-4d8a-8bae-547d3bbd6e91": {"33548400": "ok"}},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.items.update_day_orders({33548400: 1})
>>> api.commit()

Update the day orders of multiple items at once.

Required arguments

Argument Description
ids_to_orders Object A dictionary, where an item id is the key, and the day order its value: item_id: day_order.

Labels

An example label object

{
  "id": 790748,
  "name": "Label1",
  "color": 7,
  "item_order": 0,
  "is_deleted": 0
}

Properties

Property Description
id Integer The id of the label.
name String The name of the label.
color Integer The color of the label (a number between 0 and 7, or between 0 and 12 for premium users). The color codes corresponding to these numbers are: #019412, #a39d01, #e73d02, #e702a4, #9902e7, #1d02e7, #0082c5, #555555. And for the additional colors of the premium users: #008299, #03b3b2, #ac193d, #82ba00, #111111.
item_order Integer Label’s order in the label list (a number, where the smallest value should place the label at the top).
is_deleted Integer Whether the label is marked as deleted (where 1 is true and 0 is false).

Add a label

An example of adding a label:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "label_add", "temp_id": "f2f182ed-89fa-4bbb-8a42-ec6f7aa47fd0", "uuid": "ba204343-03a4-41ff-b964-95a102d12b35", "args": {"name": "Label1"}}]'
{ ...
  "sync_status": {"ba204343-03a4-41ff-b964-95a102d12b35": "ok"},
  "temp_id_mapping": {"f2f182ed-89fa-4bbb-8a42-ec6f7aa47fd0": 790748},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> label = api.labels.add('Label1')
>>> api.commit()

Add a label.

Required arguments

Argument Description
name String The name of the label (a string value).

Optional arguments

Argument Description
color Integer The color of the label (a number between 0 and 7, or between 0 and 12 for premium users).
item_order Integer Label’s order in the label list (a number, where the smallest value should place the label at the top).

Update a label

An example of updating a label:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "label_update", "uuid": "9c9a6e34-2382-4f43-a217-9ab017a83523", "args": {"id": 790748, "color": 3}}]'
{ ...
  "sync_status": {"9c9a6e34-2382-4f43-a217-9ab017a83523": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> label = api.labels.get_by_id(790748)
>>> label.update(color=3)
>>> api.commit()

Update a label.

Required arguments

Argument Description
id Integer or String (temp_id) The id of the label.

Optional arguments

Argument Description
name String The name of the label.
color Integer The color of the label (a number between 0 and 7, or between 0 and 12 for premium users).
item_order Integer Label’s order in the label list.

Delete a label

An example of deleting a label:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "label_delete", "uuid": "aabaa5e0-b91b-439c-aa83-d1b35a5e9fb3", "args": {"id": 790748}}]'
{ ...
  "sync_status": {"aabaa5e0-b91b-439c-aa83-d1b35a5e9fb3": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> label = api.labels.get_by_id(790748)
>>> label.delete()
>>> api.commit()

Delete a label.

Required arguments

Argument Description
id Integer or String (temp_id) The id of the label.

Update multiple orders

An example of updating the orders of multiple labels at once:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands=[{"type": "label_update_orders", "uuid": "1402a911-5b7a-4beb-bb1f-fb9e1ed798fb", "args": {"id_order_mapping": {"790748":  1, "790749": 2}}}]'
{ ...
  "sync_status": {
    "517560cc-f165-4ff6-947b-3adda8aef744": {
      "790748": "ok",
      "790749": "ok"
    }
  },
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.labels.update_orders({790748: 1, 790749: 2})
>>> api.commit()

Update the orders of multiple labels at once.

Required arguments

Argument Description
id_order_mapping Object A dictionary, where a label id is the key, and the order its value: label_id: order.

Notes

An example task note object

{
  "id": 17299568,
  "posted_uid": 1855589,
  "project_id": 128501470,
  "item_id": 33548400,
  "content": "Note",
  "file_attachment": {
    "file_type": "text/plain",
    "file_name": "File1.txt",
    "file_size": 1234,
    "file_url": "https://example.com/File1.txt",
    "upload_state": "completed"
  },
  "uids_to_notify": null,
  "is_deleted": 0,
  "is_archived": 0,
  "posted": "Wed 01 Oct 2014 14:54:55 +0000"
}

Notes are only available for Todoist Premium users.

Properties

Property Description
id Integer The id of the note.
posted_uid Integer The id of the user that posted the note.
item_id Integer The item which the note is part of.
project_id Integer The project which the note is part of.
content String The content of the note.
file_attachment Object A file attached to the note (see more details about attachments later on).
uids_to_notify Array of Integer A list of user ids to notify.
is_deleted Integer Whether the note is marked as deleted (where 1 is true and 0 is false).
is_archived Integer Whether the note is marked as archived (where 1 is true and 0 is false).
posted String The date when the note was posted.

File attachments

A file attachment is represented as a JSON object. The file attachment may point to a document, previously uploaded by the upload_file API call, or by any external resource.

Base file properties

Attribute Description
file_name String The name of the file.
file_size Integer The size of the file in bytes.
file_type String MIME type (for example text/plain or image/png).
file_url String The URL where the file is located. Note that we don’t cache the remote content on our servers and stream or expose files directly from third party resources. In particular this means that you should avoid providing links to non-encrypted (plain HTTP) resources, as exposing this files in Todoist may issue a browser warning.
upload_state String Upload completion state (for example pending or completed).

Image file properties

If you upload an image, you may provide thumbnail paths to ensure Todoist handles them appropriately. Valid thumbnail information is a JSON array with URL, width in pixels, height in pixels. Ex.: [“http://example.com/img.jpg”,400,300]. “Canonical” thumbnails (ones we create by upload_file API call) have the following sizes: 96x96, 288x288, 528x528.

Attribute Description
tn_l Array Large thumbnail (a list that contains the URL, the width and the height of the thumbnail).
tn_m Array Medium thumbnail (a list that contains the URL, the width and the height of the thumbnail).
tn_s Array Small thumbnail (a list that contains the URL, the width and the height of the thumbnail).

Audio file properties

If you upload an audio file, you may provide an extra attribute file_duration (duration of the audio file in seconds, which takes an integer value). In the web interface the file is rendered with a <audio> tag, so you should make sure it’s supported in current web browsers. See supported media formats for the reference.

Add a note

An example of adding a note:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "note_add", "temp_id": "59fe4461-287b-4b00-bacc-ee771137a732", "uuid": "e1005f08-acd6-4172-bab1-4338f8616e49", "args": {"item_id": 33548400, "content": "Note1"}}]'
{ ...
  "sync_status": {"e1005f08-acd6-4172-bab1-4338f8616e49": "ok"},
  "temp_id_mapping": {"59fe4461-287b-4b00-bacc-ee771137a732": 17299568},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> note = api.notes.add(33548400, 'Note1')
>>> api.commit()

Add a note.

Required arguments

Argument Description
item_id The item which the note is part of (a unique number or temp id).
content The content of the note (a string value).

Optional arguments

Argument Description
file_attachment Object A file attached to the note (see more details about attachments above, and learn how to upload a file in the Uploads section).
uids_to_notify Array of Integer A list of user ids to notify.

Add a project note

An example of adding a project note:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "note_add", "temp_id": "95653826-fc43-47b3-86c8-c11f90fe7aba", "uuid": "f5d12bd9-d14d-4529-b223-9cd7d593119e", "args": {"project_id": 128501682, "content": "Note1"}}]'
{ ...
  "sync_status": {"f5d12bd9-d14d-4529-b223-9cd7d593119e": "ok"},
  "temp_id_mapping": {"95653826-fc43-47b3-86c8-c11f90fe7aba": 17299568},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> note = api.notes.add(128501682, 'Note1')
>>> api.commit()

Add a project note.

Required arguments

Argument Description
project_id Integer or String (temp_id) The project which the note is part of.
content String The content of the note.

Optional arguments

Argument Description
file_attachment Object A file attached to the note (see more details about attachments above, and learn how to upload a file in the Uploads section).

Update a note

An example of updating a note:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "note_update", "uuid": "8a38f9c5-2cd0-4da5-87c1-26d617b354e0", "args": {"id": 17299568, "content": "UpdatedNote1"}}]'
{ ...
  "sync_status": {"8a38f9c5-2cd0-4da5-87c1-26d617b354e0": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> note api.notes.get_by_id(17299568)
>>> note.update(content='UpdatedNote1')
>>> api.commit()

Update a note.

Required arguments

Argument Description
id Integer or String (temp_id) The id of the note.

Optional arguments

Argument Description
content String The content of the note.
file_attachment Object A file attached to the note (see more details about attachments above, and learn how to upload a file in the Uploads section).

Delete a note

An example of deleting a note:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "note_delete", "uuid": "8d666fda-73c3-4677-8b04-5d223632c24f", "args": {"id": 17299568, "item_id": 33548400}}]'
{ ...
  "sync_status": {"8d666fda-73c3-4677-8b04-5d223632c24f": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> note = api.notes.get_by_id(17299568)
>>> note.delete()
>>> api.commit()

Delete a note.

Required arguments

Argument Description
id Integer or String (temp_id) The id of the note.

Uploads

Files can be uploaded to our servers and used as file attachments in Notes.

Upload a file

On success, an HTTP 200 OK with JSON data of file data is returned:

$ curl https://todoist.com/API/v7/uploads/add \
    -F token=0123456789abcdef0123456789abcdef01234567 \
    -F file_name=example.jpg \
    -F file=@/path/to/example.jpg
{
  "file_name": "example.jpg",
  "file_size": 85665,
  "file_type": "image/jpeg",
  "file_url": "https://*.cloudfront.net/*/example.jpg",
  "tn_l": [
    "https://*.cloudfront.net/tn_l_*.jpg",
    400, 309
  ],
  "tn_m": [
    "https://*.cloudfront.net/tn_m_*.jpg",
    288, 222
  ],
  "tn_s": [
    "https://*.cloudfront.net/tn_s_*.jpg",
    96, 74
  ]
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.uploads.add('example.jpg')
{
  'file_name': 'example.jpg',
  'file_size': 85665,
  'file_type': 'image/jpeg',
  'file_url': 'https://*.cloudfront.net/*/example.jpg',
  'tn_l': [
    'https://*.cloudfront.net/tn_l_*.jpg',
    400, 309
  ],
  'tn_m': [
    'https://*.cloudfront.net/tn_m_*.jpg',
    288, 222
  ],
  'tn_s': [
    'https://*.cloudfront.net/tn_s_*.jpg',
    96, 74
  ]
}

Upload a file suitable to be passed as a file_attachment attribute to the note_add or note_update calls.

Required parameters

Parameter Description
token String The user’s token received on login.
file_name String The file name to be uploaded.

Base file properties

Attribute Description
file_name String The name of the file.
file_size Integer The size of the file in bytes.
file_type String MIME type (i.e. text/plain, image/png).
file_url String The URL where the file is located (a string value representing an HTTP URL). Note that we don’t cache the remote content on our servers and stream or expose files directly from third party resources. In particular this means that you should avoid providing links to non-encrypted (plain HTTP) resources, as exposing this files in Todoist may issue a browser warning.
upload_state String Upload completion state (either pending or completed).

Image file properties

If you upload an image, you may provide thumbnail paths to ensure Todoist handles them appropriately. Valid thumbnail information is a JSON array with URL, width in pixels, height in pixels. Ex.: ["http://example.com/img.jpg",400,300]. “Canonical” thumbnails (ones we create by upload_file API call) have following sizes: 96x96, 288x288, 528x528.

Attribute Description
tn_l Array Large thumbnail (a list that contains the URL, the width and the height of the thumbnail).
tn_m Array Medium thumbnail (a list that contains the URL, the width and the height of the thumbnail).
tn_s Array Small thumbnail (a list that contains the URL, the width and the height of the thumbnail).

Audio file properties

If you upload an audio file, you may provide an extra attribute file_duration (duration of the audio file in seconds, which takes an integer value). In the web interface the file is rendered back with a <audio> tag, so you should make sure it’s supported in current web browsers. See supported media formats for the reference.

Get uploads

An example of getting the user’s uploads

$ curl https://todoist.com/API/v7/uploads/get \
    -d token=0123456789abcdef0123456789abcdef01234567
[
    {
        "file_size": 86406,
        "file_type": "image/jpeg",
        "file_url": "https://*.cloudfront.net/*/example.jpg",
        "filename": "example.jpg",
        "id": 34xx,
        "ip": "8.8.8.x",
        "item_id": 26166xxxxxx,
        "note_id": 6157xxxxxx,
        "project_id": 156996xxxxxx,
        "uploaded": "Wed 16 Dec 2015 13:18:17 +0000",
        "user_id": 5713xxxxxx
    },
    {
        "file_size": 312,
        "file_type": "text/plain",
        "file_url": "https://*.cloudfront.net/*/todo.txt",
        "filename": "todo.txt",
        "id": 34xx,
        "ip": "2.86.104.243",
        "item_id": 26166xxxxxx,
        "note_id": 6157xxxxxx,
        "project_id": 156996xxxxxx,
        "uploaded": "Wed 16 Dec 2015 12:08:14 +0000",
        "user_id": 5713xxxxxx
    }
]
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.uploads.get()
[
    {
        "file_size": 86406,
        "file_type": "image/jpeg",
        "file_url": "https://*.cloudfront.net/*/example.jpg",
        "filename": "example.jpg",
        "id": 34xx,
        "ip": "8.8.8.x",
        "item_id": 26166xxxxxx,
        "note_id": 6157xxxxxx,
        "project_id": 156996xxxxxx,
        "uploaded": "Wed 16 Dec 2015 13:18:17 +0000",
        "user_id": 5713xxxxxx
    },
    {
        "file_size": 312,
        "file_type": "text/plain",
        "file_url": "https://*.cloudfront.net/*/todo.txt",
        "filename": "todo.txt",
        "id": 34xx,
        "ip": "2.86.104.243",
        "item_id": 26166xxxxxx,
        "note_id": 6157xxxxxx,
        "project_id": 156996xxxxxx,
        "uploaded": "Wed 16 Dec 2015 12:08:14 +0000",
        "user_id": 5713xxxxxx
    }
]

Get all user’s uploads.

Required parameters

Parameter Description
token String The user’s token received on login (a string hash value).

Optional parameters

Parameter Description
limit Integer The number of items to return (a number, where the default is 30, and the maximum is 50).
last_id Integer Can be used for pagination. This should be the minimum upload id you’ve fetched so far. All results will be listed before that id.

Delete upload

An example of deleting an upload

$ curl https://todoist.com/API/v7/uploads/delete \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d file_url='https://*.cloudfront.net/*/example.jpg'
"ok"
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.uploads.delete('https://*.cloudfront.net/*/example.jpg')
ok

Delete an upload.

Required parameters

Parameter Description
token String The user’s token received on login (a string hash value).
file_url String The file URL to delete.

Filters

An example filter object

{
  "id": 4638878,
  "name": "Priority 1",
  "query": "priority 1",
  "color": 6,
  "item_order": 3,
  "is_deleted": 0
}

Filters are only available for Todoist Premium users.

Properties

Property Description
id Integer The id of the filter.
name String The name of the filter.
query String The query to search for. Examples of searches can be found in the Todoist help page.
color Integer The color of the filter (between 0 and 7, or between 0 and 12 for premium users). The color codes corresponding to these numbers are: #019412, #a39d01, #e73d02, #e702a4, #9902e7, #1d02e7, #0082c5, #555555. And for the additional colors of the premium users: #008299, #03b3b2, #ac193d, #82ba00, #111111.
item_order Integer Filter’s order in the filter list (where the smallest value should place the filter at the top).
is_deleted Integer Whether the filter is marked as deleted (where 1 is true and 0 is false).

Add a filter

An example of adding a filter:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "filter_add", "temp_id": "9204ca9f-e91c-436b-b408-ea02b3972686", "uuid": "0b8690b8-59e6-4d5b-9c08-6b4f1e8e0eb8", "args": {"name": "Filter1", "query": "no due date"}}]'
{ ...
  "sync_status": {"0b8690b8-59e6-4d5b-9c08-6b4f1e8e0eb8": "ok"},
  "temp_id_mapping": {"9204ca9f-e91c-436b-b408-ea02b3972686": 9},
  ... }

>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> filter = api.filters.add('Filter1', 'no due date')
>>> api.commit()

Add a filter.

Required arguments

Argument Description
name String The name of the filter.
query String The query to search for. Examples of searches can be found in the Todoist help page.

Optional arguments

Argument Description
color Integer The color of the filter (between 0 and 7, or between 0 and 12 for premium users).
item_order Integer Filter’s order in the filter list (the smallest value should place the filter at the top).

Update a filter

An example of updating a filter:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "filter_update", "uuid": "a68b588a-44f7-434c-b3c5-a699949f755c", "args": {"id": 9, "query": "tomorrow"}}]'
{ ...
  "sync_status": {"a68b588a-44f7-434c-b3c5-a699949f755c": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> filter = api.filters.get_by_id(9)
>>> filter.update(query='tomorrow')
>>> api.commit()

Update a filter.

Required arguments

Argument Description
id Integer or String (temp_id) The id of the filter.

Optional arguments

Argument Description
name The name of the filter (a string value).
query The query to search for. Examples of searches can be found in the Todoist help page.
color The color of the filter (between 0 and 7, or between 0 and 12 for premium users).
item_order Filter’s order in the filter list (where the smallest value should place the filter at the top).

Delete a filter

An example of deleting a filter:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "filter_delete", "uuid": "b8186025-66d5-4eae-b0dd-befa541abbed", "args": {"id": 9}}]'
{ ...
  "sync_status": {"b8186025-66d5-4eae-b0dd-befa541abbed": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> filter = api.filters.get_by_id(9)
>>> filter.delete()
>>> api.commit()

Delete a filter.

Required arguments

Argument Description
id Integer or String (temp_id) The id of the filter.

Update multiple orders

An example of updating the orders of multiple filters at once:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands=[{"type": "filter_update_orders", "uuid": "517560cc-f165-4ff6-947b-3adda8aef744", "args": {"id_order_mapping": {"9":  1, "10": 2}}}]'
{ ...
  "sync_status": {
    "517560cc-f165-4ff6-947b-3adda8aef744": {
      "9": "ok",
      "10": "ok"
    }
  },
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.filters.update_orders({9: 1, 10: 2})
>>> api.commit()

Update the orders of multiple filters at once.

Required arguments

Argument Description
id_order_mapping Object A dictionary, where a filter id is the key, and the order its value: filter_id: order.

Reminders

An example reminder object

{
  "id": 12763422,
  "notify_uid": 1855589,
  "item_id": 33511505,
  "service": "email",
  "type": "absolute",
  "date_string": "Oct 6 @ 2pm",
  "date_lang" : "en",
  "due_date_utc": "Mon 06 Oct 2014 11:00:00 +0000",
  "mm_offset": 180,
  "is_deleted": 0
}

Reminders are only available for Todoist Premium users.

Properties

Property Description
id Integer The id of the reminder.
notify_uid Integer The user id which should be notified of the reminder, typically the current user id creating the reminder.
item_id Integer The item id for which the reminder is about.
service String The way to get notified of the reminder: email for e-mail, mobile for mobile text message, or push for mobile push notification.
type String The type of the reminder: relative for a time-based reminder specified in minutes from now, absolute for a time-based reminder with a specific time and date in the future, and location for a location-based reminder.
date_string String The date of the reminder, added in free form text, for example it can be every day @ 10 (or null or an empty string if not set). Look at our reference to see which formats are supported.
date_lang String The language of the date_string (valid languages are: en, da, pl, zh, ko, de, pt, ja, it, fr, sv, ru, es, nl).
due_date_utc String The date of the reminder in a format like Mon 07 Aug 2006 12:34:56 +0100 (or null if not set).
mm_offset Integer The relative time in minutes before the due date of the item, in which the reminder should be triggered. Note, that the item should have a due date set in order to add a relative reminder.
name String An alias name for the location.
loc_lat String The location latitude.
loc_long String The location longitude.
loc_trigger String What should trigger the reminder: on_enter for entering the location, or on_leave for leaving the location.
radius Integer The radius around the location that is still considered as part of the location (in meters).
is_deleted Integer Whether the reminder is marked as deleted (where 1 is true and 0 is false).

Add a reminder

An example of adding a relative reminder:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "reminder_add", "temp_id": "e24ad822-a0df-4b7d-840f-83a5424a484a", "uuid": "41e59a76-3430-4e44-92b9-09d114be0d49", "args": {"item_id": 33511505, "service": "email", "minute_offset": 30}}]'
{ ...
  "sync_status": {"41e59a76-3430-4e44-92b9-09d114be0d49": "ok"},
  "temp_id_mapping": {"e24ad822-a0df-4b7d-840f-83a5424a484a": 12763422},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> reminder = api.reminders.add(33511505, service='email', minute_offset=30)
>>> api.commit()

An example of adding an absolute reminder:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "reminder_add", "temp_id": "952a365e-4965-4113-b4f4-80cdfcada172u", "uuid": "e7c8be2d-f484-4852-9422-a9984c58b1cd", "args": {"item_id": 33511505, "service": "email", "due_date_utc": "2014-10-15T11:00"}}]'
{ ...
  "sync_status": {"e7c8be2d-f484-4852-9422-a9984c58b1cd": "ok"},
  "temp_id_mapping": {"952a365e-4965-4113-b4f4-80cdfcada172": 12763422},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> reminder = api.reminders.add(33511505, service='email', due_date_utc='2014-10-15T11:00')
>>> api.commit()

An example of adding a location reminder:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "reminder_add", "temp_id": "7ad9609d-579f-4828-95c5-3600acdb2c81", "uuid": "830cf409-daba-479c-a624-68eb0c07d01c", "args": {"item_id": 33511505, "service": "email", "type": "location", "name": "Aliados", "loc_lat": "41.148581", "loc_long":"-8.610945000000015", "loc_trigger":"on_enter", "radius": 100}}]'
{ ...
  "sync_status": {"830cf409-daba-479c-a624-68eb0c07d01c": "ok"},
  "temp_id_mapping": {"7ad9609d-579f-4828-95c5-3600acdb2c81": 12763422},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> reminder = api.reminders.add(33511505, service='email', type='location', name='Aliados', loc_lat='41.148581', loc_long='-8.610945000000015', loc_trigger='on_enter', radius=100)
>>> api.commit()

Add a reminder.

Required arguments

Argument Description
item_id Integer or String (temp_id) The item id for which the reminder is about.

Optional arguments

Argument Description
notify_uid Integer The user id which should be notified of the reminder, typically the current user id creating the reminder.
service String The way to get notified of the reminder: email for e-mail, mobile for mobile text message, or push for mobile push notification.
type String The type of the reminder: relative for a time-based reminder specified in minutes from now, absolute for a time-based reminder with a specific time and date in the future, and location for a location-based reminder.
date_string String The date of the reminder, added in free form text, for example it can be every day @ 10 (or null or an empty string to unset). Look at our reference to see which formats are supported.
date_lang String The language of the date_string (valid languages are: en, da, pl, zh, ko, de, pt, ja, it, fr, sv, ru, es, nl).
due_date_utc String The date of the reminder in the format YYYY-MM-DDTHH:MM (for example: 2012-3-24T23:59). The value of due_date_utc must be in UTC. Either due_date_utc or date_string can be used to set the reminder date, but the value of due_date_utc takes precedence over the value of date_string.
minute_offset Integer The relative time in minutes before the due date of the item, in which the reminder should be triggered. Note, that the item should have a due date set in order to add a relative reminder.
name String An alias name for the location.
loc_lat String The location latitude.
loc_long String The location longitude.
loc_trigger String What should trigger the reminder: on_enter for entering the location, or on_leave for leaving the location.
radius Integer The radius around the location that is still considered as part of the location (in meters).

Update a reminder

An example of updating a reminder:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "reminder_update", "uuid": "b0e7562e-ea9f-4c84-87ee-9cbf9c103234", "args": {"id": 12763422, "due_date_utc": "2014-10-10T15:00"}}]'
{ ...
  "sync_status": {"b0e7562e-ea9f-4c84-87ee-9cbf9c103234": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> reminder = api.reminders.get_by_id(12763422)
>>> reminder.update(due_date_utc='2014-10-10T15:00')
>>> api.commit()

Update a reminder.

Required arguments

Argument Description
id Integer or String (temp_id) The id of the reminder.

Optional arguments

Argument Description
notify_uid Integer The user id which should be notified of the reminder, typically the current user id creating the reminder.
service String The way to get notified of the reminder: email for e-mail, mobile for mobile text message, or push for mobile push notification.
type String The type of the reminder: relative for a time-based reminder specified in minutes from now, absolute for a time-based reminder with a specific time and date in the future, and location for a location-based reminder.
date_string String The date of the reminder, added in free form text, for example it can be every day @ 10 (or null or an empty string to unset). Look at our reference to see which formats are supported.
date_lang String The language of the date_string (valid languages are: en, da, pl, zh, ko, de, pt, ja, it, fr, sv, ru, es, nl).
due_date_utc String The date of the reminder in the format YYYY-MM-DDTHH:MM (for example: 2012-3-24T23:59). Either due_date_utc or date_string can be used to set the reminder date, but the value of due_date_utc takes precedence over the value of date_string.
minute_offset Integer The relative time in minutes before the due date of the item, in which the reminder should be triggered. Note, that the item should have a due date set in order to add a relative reminder.
name String An alias name for the location.
loc_lat String The location latitude.
loc_long String The location longitude.
loc_trigger String What should trigger the reminder: on_enter for entering the location, or on_leave for leaving the location.
radius Integer The radius around the location that is still considered as part of the location (in meters).

Delete a reminder

An example of deleting a reminder:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "reminder_delete", "uuid": "0896d03b-eb90-49f7-9020-5ed3fd09df2d", "args": {"id": 9}}]'
{ ...
  "sync_status": {"0896d03b-eb90-49f7-9020-5ed3fd09df2d": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> reminder = api.reminders.get_by_id(12763422)
>>> reminder.delete()
>>> api.commit()

Delete a reminder.

Required arguments

Argument Description
id Integer or String (temp_id) The id of the filter.

Clear the locations

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "clear_locations", "uuid": "d285ae02-80c6-477c-bfa9-45272d7bddfb", "args": {}}]'
{ ...
  "sync_status": {"d285ae02-80c6-477c-bfa9-45272d7bddfb": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> reminder = api.locations.clear()
>>> api.commit()

Clears the locations list, which is used for the location reminders.

Miscellaneous

Get productivity stats

An example of getting the user’s productivity stats:

$ curl https://todoist.com/API/v7/completed/get_stats \
    -d token=0123456789abcdef0123456789abcdef01234567
{
  "karma_last_update": 50.0,
  "karma_trend": "up",
  "days_items": [
    { "date": "2014-11-03",
      "items": [],
      "total_completed": 0 },
  ],
  "completed_count": 0,
  "karma_update_reasons": [
    { "positive_karma_reasons": [4],
      "new_karma": 50.0,
      "negative_karma": 0.0,
      "positive_karma": 50.0,
      "negative_karma_reasons": [],
      "time": "Mon 20 Oct 2014 12:06:52"}
  ],
  "karma": 50.0,
  "week_items": [
    { "date": "2014-11-03\/2014-11-09",
      "items": [],
      "total_completed": 0 },
  ],
  "project_colors": {},
  "karma_graph": "https:\/\/todoist.com\/chart?cht=lc&chs=255x70&chd=s:A9&chco=dd4b39&chf=bg,s,ffffff&chxt=x,y&chxl=0:%7cMo%2C%2020%7c%7c1:%7c0%7c50&chxs=0,999999%7c1,999999",
  "goals": {
    "karma_disabled": 0,
    "user_id": 4,
    "max_weekly_streak": {
      "count": 0,
      "start": "",
      "end": ""
    },
    "ignore_days": [6, 7],
    "vacation_mode": 0,
    "current_weekly_streak": {
      "count": 0,
      "start": "",
      "end": ""
    },
    "current_daily_streak": {
      "count": 0,
      "start": "",
      "end": ""
    },
    "weekly_goal": 25,
    "max_daily_streak": {
      "count": 0,
      "start": "",
      "end": ""
    },
    "daily_goal": 5
  }
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.completed.get_stats()
{
  'karma_last_update': 50.0,
  'karma_trend': 'up',
  'days_items': [
    { 'date': '2014-11-03',
      'items': [],
      'total_completed': 0}
  ],
  'completed_count': 0,
  'karma_update_reasons': [
    { 'positive_karma_reasons': [4],
      'new_karma': 50.0,
      'negative_karma': 0.0,
      'positive_karma': 50.0,
      'negative_karma_reasons': [],
      'time': 'Mon 20 Oct 2014 12:06:52' }
  ],
  'karma': 50.0,
  'week_items': [
    { 'date': '2014-11-03/2014-11-09',
      'items': [],
      'total_completed': 0 },
  ],
  'project_colors': {},
  'karma_graph': 'https://todoist.com/chart?cht=lc&chs=255x70&chd=s:A9&chco=dd4b39&chf=bg,s,ffffff&chxt=x,y&chxl=0:%7cMo%2C%2020%7c%7c1:%7c0%7c50&chxs=0,999999%7c1,999999',
  'goals': {
    'karma_disabled': 0,
    'user_id': 4,
    'max_weekly_streak': {
      'count': 0,
      'start': '',
      'end': ''
    },
    'ignore_days': [6, 7],
    'vacation_mode': 0,
    'current_weekly_streak': {
      'count': 0,
      'start': '',
      'end': ''
    },
    'current_daily_streak': {
      'count': 0,
      'start': '',
      'end': ''
    },
    'weekly_goal': 25,
    'max_daily_streak': {
      'count': 0,
      'start': '',
      'end': ''
    },
    'daily_goal': 5
  }
}

Get the user’s productivity stats.

Required parameters

Parameter Description
token String The user’s token received on login.

Get all completed items

An example of getting the user’s completed tasks

$ curl https://todoist.com/API/v7/completed/get_all \
    -d token=0123456789abcdef0123456789abcdef01234567
{
  "items": [
    { "content": "Item11",
      "meta_data": null,
      "user_id": 1855589,
      "task_id": 33511505,
      "note_count": 0,
      "project_id": 128501470,
      "completed_date": "Tue 17 Feb 2015 15:40:41 +0000",
      "id": 33511505
    }
  ],
  "projects": {
    "128501470":
    { "color": 7,
      "collapsed": 0,
      "indent": 1,
      "is_deleted": 0,
      "id": 128501470,
      "user_id": 1855589,
      "name": "Project1",
      "item_order": 36,
      "is_archived": 0 }
  }
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.completed.get_all()
{
  'items': [
    { 'user_id': 1855589,
      'task_id': 33511505,
      'note_count': 0,
      'completed_date': 'Tue 17 Feb 2015 15:40:41 +0000',
      'content': 'Item1',
      'meta_data': None,
      'project_id': 128501470,
      'id': 33511505},
  ],
  'projects': {
    '128501470':
      { 'name': 'Inbox',
        'user_id': 1855589,
        'color': 7,
        'is_deleted': 0,
        'collapsed': 0,
        'inbox_project': True,
        'item_order': 36,
        'is_archived': 0,
        'indent': 1,
        'id': 128501470 }
  }
}

Get all the user’s completed items (tasks). Only available for Todoist Premium users.

Required parameters

Parameter Description
token String The user’s token received on login.

Optional parameters

Parameter Description
project_id Integer Filter the tasks by project id.
limit Integer The number of items to return (where the default is 30, and the maximum is 50).
offset Integer Can be used for pagination, when more than the limit number of tasks are returned.
until String Return items with a completed date same or older than until (a string value formatted as 2007-4-29T10:13).
since String Return items with a completed date newer than since (a string value formatted as 2007-4-29T10:13).
annotate_notes Boolean Return notes together with the completed items (a true or false value).

Get archived projects

An example of getting the user’s archived projects

$ curl https://todoist.com/API/v7/projects/get_archived \
    -d token=0123456789abcdef0123456789abcdef01234567
[
  {
    "id" : 150977840,
    "name" : "Project1",
    "item_order" : 1,
    "indent" : 1,
    "color" : 7,
    "collapsed" : 0
    "is_archived" : 1,
    "is_deleted" : 0,
  }
]
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.projects.get_archived()
[
  {
    'id' : 150977840,
    'name' : 'Project1',
    'item_order' : 1,
    'indent' : 1,
    'color' : 7,
    'collapsed' : 0
    'is_archived' : 1,
    'is_deleted' : 0,
  }
]

Get the user’s archived projects.

Required parameters

Parameter Description
token String The user’s token received on login.

Add item

An example of adding a task:

$ curl https://todoist.com/API/v7/items/add \
    -d token=0123456789abcdef0123456789abcdef01234567
    -d content=Task1
{
  "assigned_by_uid": 1855589,
  "is_archived": 0,
  "labels": [],
  "sync_id": null,
  "in_history": 0,
  "date_added": "Wed 18 Feb 2015 11:09:11 +0000",
  "indent": 1,
  "children": null,
  "content": "Task1",
  "is_deleted": 0,
  "user_id": 1855589,
  "due_date_utc": null,
  "id": 33548400,
  "priority": 4,
  "item_order": 1,
  "responsible_uid": null,
  "project_id": 128501411,
  "collapsed": 0,
  "checked": 0,
  "date_string": "" }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.add_item("Task1")
{ 'is_archived': 0,
  'labels': [],
  'sync_id': None,
  'in_history': 0,
  'checked': 0,
  'id': 33548400,
  'priority': 4,
  'user_id': 1855589,
  'date_added': 'Wed 18 Feb 2015 11:09:11 +0000',
  'children': None,
  'content': 'Task1',
  'item_order': 1,
  'project_id': 128501411,
  'date_string': '',
  'assigned_by_uid': 1855589,
  'collapsed': 0,
  'indent': 1,
  'is_deleted': 0,
  'due_date_utc': None,
  'responsible_uid': None }

Add a new task to a project. Note, that this is provided as a helper method, a shortcut, to quickly add a task without going through the Sync workflow described in a previous section.

Required parameters

Parameter Description
token String The user’s token received on login.
content String The text of the task.

Optional parameters

Parameter Description
project_id Integer The id of the project to add the task to, while the default is the user’s Inbox project.
date_string String The date of the task, added in free form text, for example it can be every day @ 10 (or null or an empty string to unset). Look at our reference to see which formats are supported.
priority Integer The priority of the task (between 1 and 4, 4 for very urgent and 1 for natural).
indent Integer The indent of the task (between 1 and 4, where 1 is top-level).
item_order Integer The order of the task inside a project (where the smallest value would place the task at the top).
labels Array of Integer The task’s labels (a list of label ids such as [2324,2525]).
assigned_by_uid Integer The id of the user who assigns the current task. This makes sense for shared projects only. Accepts 0 or any user id from the list of project collaborators. If this value is unset or invalid, it will automatically be set up to your uid.
responsible_uid Integer The id of user who is responsible for accomplishing the current task. This makes sense for shared projects only. Accepts 0 or any user id from the list of project collaborators. If this value is unset or invalid, it will automatically be set to null.
note String Add a note directly to the task (a string value that will become the content of the note).

Get item info

An example of getting an item’s info:

$ curl https://todoist.com/API/v7/items/get \
    -d token=0123456789abcdef0123456789abcdef01234567
    -d item_id=466
{
  "project": {
    "name": "Inbox",
    "color": 7,
    "is_deleted": 0,
    "collapsed": 0,
    "inbox_project": true,
    "item_order": 0,
    "indent": 1,
    "id": 1,
    "shared": false,
    "is_archived": 0
  },
  "item": {
    "assigned_by_uid": 1,
    "due_date_utc": null,
    "is_archived": 0,
    "labels": [],
    "sync_id": null,
    "in_history": 0,
    "date_added": "Tue 22 Mar 2016 16:00:00 +0000",
    "checked": 0,
    "date_lang": "en",
    "id": 466,
    "content": "foo",
    "indent": 1,
    "user_id": 1,
    "is_deleted": 0,
    "priority": 1,
    "item_order": 1,
    "responsible_uid": null,
    "project_id": 1,
    "collapsed": 0,
    "date_string": null
  },
  "notes": [
    {
      "is_deleted": 0,
      "is_archived": 0,
      "file_attachment": null,
      "content": "1",
      "posted_uid": 1,
      "uids_to_notify": null,
      "item_id": 466,
      "project_id": 1,
      "id": 36,
      "posted": "Wed 18 May 2016 16:45:00 +0000"
    },
    {
      "is_deleted": 0,
      "is_archived": 0,
      "file_attachment": null,
      "content": "2",
      "posted_uid": 1,
      "uids_to_notify": null,
      "item_id": 466,
      "project_id": 1,
      "id": 37,
      "posted": "Wed 18 May 2016 16:45:00 +0000"
    },
    {
      "is_deleted": 0,
      "is_archived": 0,
      "file_attachment": null,
      "content": "3",
      "posted_uid": 1,
      "uids_to_notify": null,
      "item_id": 466,
      "project_id": 1,
      "id": 38,
      "posted": "Wed 18 May 2016 16:45:00 +0000"
    }
  ]
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.items.get(466)
{
  'project': {
    'name': 'Inbox',
    'color': 7,
    'is_deleted': 0,
    'collapsed': 0,
    'inbox_project': true,
    'item_order': 0,
    'indent': 1,
    'id': 1,
    'shared': false,
    'is_archived': 0
  },
  'item': {
    'assigned_by_uid': 1,
    'due_date_utc': null,
    'is_archived': 0,
    'labels': [],
    'sync_id': null,
    'in_history': 0,
    'date_added': 'Tue 22 Mar 2016 16:00:00 +0000',
    'checked': 0,
    'date_lang': 'en',
    'id': 466,
    'content': 'foo',
    'indent': 1,
    'user_id': 1,
    'is_deleted': 0,
    'priority': 1,
    'item_order': 1,
    'responsible_uid': null,
    'project_id': 1,
    'collapsed': 0,
    'date_string': null
  },
  'notes': [
    {
      'is_deleted': 0,
      'is_archived': 0,
      'file_attachment': null,
      'content': '1',
      'posted_uid': 1,
      'uids_to_notify': null,
      'item_id': 466,
      'project_id': 1,
      'id': 36,
      'posted': 'Wed 18 May 2016 16:45:00 +0000'
    },
    {
      'is_deleted': 0,
      'is_archived': 0,
      'file_attachment': null,
      'content': '2',
      'posted_uid': 1,
      'uids_to_notify': null,
      'item_id': 466,
      'project_id': 1,
      'id': 37,
      'posted': 'Wed 18 May 2016 16:45:00 +0000'
    },
    {
      'is_deleted': 0,
      'is_archived': 0,
      'file_attachment': null,
      'content': '3',
      'posted_uid': 1,
      'uids_to_notify': null,
      'item_id': 466,
      'project_id': 1,
      'id': 38,
      'posted': 'Wed 18 May 2016 16:45:00 +0000'
    }
  ]
}

This function is used to extract detailed information about the item, including all the notes.

It’s especially important, because on initial load we return back no more than 10 last notes, and if client wants to get more, they can be downloaded with get_item endpoint.

It returns a JSON object with the item, and optionally the project and notes attributes.

Required parameters

Parameter Description
token String The user’s token received on login.
item_id Integer The item’s unique id.
all_data Boolean Whether to return the parent project and notes of the item (a true or false value, while the default is true).

Get project info

An example of getting a project’s info:

$ curl https://todoist.com/API/v7/projects/get \
    -d token=0123456789abcdef0123456789abcdef01234567
    -d project_id=128501682
{
  "project" : {
    "id": 128501682,
    "name": "Project1",
    "color": 1,
    "indent": 1,
    "item_order": 36,
    "collapsed": 0,
    "shared": false,
    "is_deleted": 0,
    "is_archived": 0,
  },
  "notes" : [
    {
      "is_deleted": 0,
      "is_archived": 0,
      "file_attachment": null,
      "content": "Note1",
      "posted_uid": 1,
      "uids_to_notify": null,
      "project_id": 128501682,
      "id": 17299568,
      "posted": "Wed 18 May 2016 16:45:00 +0000"
    },
  ]
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.projects.get(128501682)
{
  "project" : {
    'id': 128501682,
    'name': 'Project1',
    'color': 1,
    'indent': 1,
    'item_order': 36,
    'collapsed': 0,
    'shared': false,
    'is_deleted': 0,
    'is_archived': 0,
  },
  "notes" : [
    {
      'is_deleted': 0,
      'is_archived': 0,
      'file_attachment': null,
      'content': 'Note1',
      'posted_uid': 1,
      'uids_to_notify': null,
      'project_id': 128501682,
      'id': 17299568,
      'posted': 'Wed 18 May 2016 16:45:00 +0000'
    },
  ]
}

This function is used to extract detailed information about the project, including all the notes.

It’s especially important, because on initial load we return back no more than 10 last notes, and if client wants to get more, they can be downloaded with get_project endpoint.

It returns a JSON object with the project, and optionally the notes attributes.

Required parameters

Parameter Description
token String The user’s token received on login.
project_id Integer The projects’s unique id.
all_data Boolean Whether to return the notes of the project (a true or false value, while the default is true).

Get project data

An example of getting a project’s data:

$ curl https://todoist.com/API/v7/projects/get_data \
    -d token=0123456789abcdef0123456789abcdef01234567
    -d project_id=128501682
{
  "project" : {
    "item_order" : 4,
    "user_id" : 1855589,
    "is_archived" : 0,
    "is_deleted" : 0,
    "id" : 175655925,
    "archived_date" : null,
    "collapsed" : 0,
    "indent" : 1,
    "archived_timestamp" : 0,
    "color" : 7,
    "name" : "Project1"
  },
  "items" : [
    {
      "is_deleted" : 0,
      "date_string" : "",
      "date_added" : "Tue 19 Jul 2016 12:50:49 +0000",
      "item_order" : 1,
      "responsible_uid" : null,
      "due_date" : null,
      "content" : "Task1",
      "id" : 101964377,
      "user_id" : 1855589,
      "date_lang" : "en",
      "assigned_by_uid" : 1855589,
      "in_history" : 0,
      "is_archived" : 0,
      "project_id" : 175655925,
      "sync_id" : null,
      "collapsed" : 0,
      "due_date_utc" : null,
      "indent" : 1,
      "labels" : [],
      "checked" : 0,
      "priority" : 1
    }
  ]
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.projects.get_data(128501682)
{
  'project' : {
    'item_order' : 4,
    'user_id' : 1855589,
    'is_archived' : 0,
    'is_deleted' : 0,
    'id' : 175655925,
    'archived_date' : None,
    'collapsed' : 0,
    'indent' : 1,
    'archived_timestamp' : 0,
    'color' : 7,
    'name' : 'Project1'
  },
  'items' : [
    {
      'is_deleted' : 0,
      'date_string' : '',
      'date_added' : 'Tue 19 Jul 2016 12:50:49 +0000',
      'item_order' : 1,
      'responsible_uid' : None,
      'due_date' : None,
      'content' : 'Task1',
      'id' : 101964377,
      'user_id' : 1855589,
      'date_lang' : 'en',
      'assigned_by_uid' : 1855589,
      'in_history' : 0,
      'is_archived' : 0,
      'project_id' : 175655925,
      'sync_id' : None,
      'collapsed' : 0,
      'due_date_utc' : None,
      'indent' : 1,
      'labels' : [],
      'checked' : 0,
      'priority' : 1
    }
  ]
}

Get a project’s uncompleted items.

User

A user in Todoist is a JSON object. The dates will be in the UTC timezone. Typically a user object will have the following properties:

An example user object

{
  "id": 1855589,
  "token": "0123456789abcdef0123456789abcdef01234567",
  "email": "me@xample.com",
  "full_name": "Example User",
  "inbox_project": 128501411,
  "tz_info" : {
     "timezone" : "Europe/Athens",
     "minutes" : 0,
     "hours" : 3,
     "is_dst" : 1,
     "gmt_string" : "+03:00"
  },
  "start_page": "overdue, 7 days",
  "start_day": 1,
  "next_week": 1,
  "date_format": 0,
  "time_format": 0,
  "sort_order": 0,
  "default_reminder": null,
  "auto_reminder" : 30,
  "mobile_host": null,
  "mobile_number": null,
  "completed_count": 20,
  "completed_today" : 2,
  "karma": 684.0,
  "karma_trend": "-",
  "is_premium": false,
  "premium_until": null,
  "is_biz_admin": false,
  "business_account_id": null,
  "image_id": null,
  "avatar_small" : "https://*.cloudfront.net/*_small.jpg",
  "avatar_medium" : "https://*.cloudfront.net/*_medium.jpg",
  "avatar_big" : "https://*.cloudfront.net/*_big.jpg",
  "avatar_s640" : "https://*.cloudfront.net/*_s640.jpg",
  "theme" : 0,
  "features" : {
    "beta": 0,
    "restriction" : 3,
    "has_push_reminders": false,
  },
  "join_date": "Wed 30 Apr 2014 13:24:38 +0000"
}

Properties

Property Description
id Integer The user’s id.
token String The user’s token that should be used to call the other API methods.
email String The user’s email.
full_name String The user’s real name formatted as Firstname Lastname.
inbox_project Integer The id of the user’s Inbox project.
tz_info Object The user’s timezone (a dictionary structure), which includes the following elements: the timezone as a string value, the hours and minutes difference from GMT, whether daylight saving time applies denoted by is_dst, and a string value of the time difference from GMT that is gmt_string.
start_page String The user’s default view on Todoist. The start page can be one of the following: _info_page for the info page, _blank for a blank page, _project_<PROJECT_ID> for project with id <PROJECT_ID>, and <ANY_QUERY> to query after anything.
start_day Integer The first day of the week (between 1 and 7, where 1 is Monday and 7 is Sunday).
next_week Integer The day of the next week, that tasks will be postponed to (between 1 and 7, where 1 is Monday and 7 is Sunday).
time_format Integer Whether to use a 24h format such as 13:00 (if set to 0) when displaying time, or a 12h format such as 1:00pm (if set to 1).
date_format Integer Whether to use the DD-MM-YYYY date format (if set to 0), or the MM-DD-YYYY format (if set to 1).
sort_order Integer Whether to show projects in an oldest dates first order (if set to 0, or a oldest dates last order (if set to 1).
default_reminder String The default reminder for the user. Reminders are only possible for Premium users. The default reminder can be one of the following: email to send reminders by email, mobile to send reminders to mobile devices via SMS, push to send reminders to smart devices using push notifications (one of the Android or iOS official clients must be installed on the client side to receive these notifications), no_default to turn off sending default reminders.
auto_reminder Integer The default time in minutes for the automatic reminders set, whenever a due date has been specified for a task.
mobile_number String The user’s mobile number (null if not set).
mobile_host String The user’s mobile host (null if not set).
completed_count Integer The total number of completed tasks.
completed_today Integer The number of completed tasks for today.
karma Number The user’s karma score.
karma_trend String The user’s karma trend (for example up).
is_premium String Whether the user has a Premium subscription (a true or false value).
premium_until String The date when the user’s Premium subscription ends (null if not a Premium user).
is_biz_admin String Whether the user is a business account administrator (a true or false value).
business_account_id Integer The id of the user’s business account.
image_id String The id of the user’s avatar.
avatar_small String The link to a 35x35 pixels image of the user’s avatar.
avatar_medium String The link to a 60x60 pixels image of the user’s avatar.
avatar_big String The link to a 195x195 pixels image of the user’s avatar.
avatar_s640 String The link to a 640x640 pixels image of the user’s avatar.
theme Integer The currently selected Todoist theme (a number between 0 and 10).
features Object Used internally for any special features that apply to the user. Current special features include whether any special restriction applies to the user, whether the user is in beta status, whether the user has_push_reminders enabled, and whether dateist_inline_disabled that is inline date parsing support is disabled.
join_date String The date when the user joined Todoist.

Register a new user

An example of registering a new user:

$ curl https://todoist.com/API/v7/user/register \
    -d email=me@example.com \
    -d full_name=Example\ User \
    -d password=secret
{
  "id": 1855589,
  "token": "0123456789abcdef0123456789abcdef01234567",
  "email": "me@xample.com",
  "full_name": "Example User",
  "inbox_project": 128501411,
  "tz_info": {
    "timezone": "GMT +1:00",
    "gmt_string": "+01:00",
    "hours": 1,
    "minutes": 0,
    "is_dst": 0
  },
  "start_page": "overdue, 7 days",
  "start_day": 1,
  "next_week": 1,
  "date_format": 0,
  "time_format": 0,
  "sort_order": 0,
  "default_reminder": null,
  "auto_reminder" : 30,
  "mobile_host": null,
  "mobile_number": null,
  "completed_count": 20,
  "completed_today" : 2,
  "karma": 684.0,
  "karma_trend": "-",
  "is_premium": false,
  "premium_until": null,
  "is_biz_admin": false,
  "business_account_id": null,
  "image_id": null,
  "avatar_small" : "https://*.cloudfront.net/*_small.jpg",
  "avatar_medium" : "https://*.cloudfront.net/*_medium.jpg",
  "avatar_big" : "https://*.cloudfront.net/*_big.jpg",
  "avatar_s640" : "https://*.cloudfront.net/*_s640.jpg",
  "theme" : 0,
  "features" : {
    "beta": 0,
    "restriction" : 3,
    "has_push_reminders": false,
  },
  "join_date": "Wed 30 Apr 2014 13:24:38 +0000"
}
>>> import todoist
>>> api = todoist.TodoistAPI()
>>> api.user.register('me@example.com', 'Example User', 'secret')
{
  'id': 1855589,
  'token': '0123456789abcdef0123456789abcdef01234567',
  'email': 'me@exampe.com',
  'full_name': 'Example User',
  'inbox_project': 128501411,
  'tz_info': {
    'timezone': 'GMT +1:00',
    'gmt_string': '+01:00',
    'hours': 1,
    'minutes': 0,
    'is_dst': 0
  },
  'start_page': 'overdue, 7 days',
  'start_day': 1,
  'next_week': 1,
  'date_format': 0,
  'time_format': 0,
  'sort_order': 0,
  'default_reminder': None,
  'auto_reminder' : 30,
  'mobile_host': None,
  'mobile_number': None,
  'completed_count': 20,
  'completed_today' : 2,
  'karma': 684.0,
  'karma_trend': '-',
  'is_premium': False,
  'premium_until': None,
  'is_biz_admin': False,
  'business_account_id': None,
  'image_id': None,
  'avatar_small' : 'https://*.cloudfront.net/*_small.jpg',
  'avatar_medium' : 'https://*.cloudfront.net/*_medium.jpg',
  'avatar_big' : 'https://*.cloudfront.net/*_big.jpg',
  'avatar_s640' : 'https://*.cloudfront.net/*_s640.jpg',
  'theme' : 0,
  'features' : {
    'beta': 0,
    'restriction' : 3,
    'has_push_reminders': false,
  },
  'join_date': 'Wed 30 Apr 2014 13:24:38 +0000',
}

Register a new user.

Required parameters

Parameter Description
email String The user’s email.
full_name String The user’s real name formatted as Firstname Lastname.
password String The user’s password.

Optional parameters

Parameter Description
lang String The user’s language, which can take one of the following values: de, fr, ja, pl, pt_BR, zh_CN, es, hi, ko, pt, ru, zh_TW.
timezone String The user’s timezone (a string value such as UTC, Europe/Lisbon, US/Eastern, Asian/Taipei). By default we use the user’s IP address to determine the timezone.

Delete an existing user

An example of deleting an existing user:

$ curl https://todoist.com/API/v7/user/delete \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d current_password=secret
"ok"
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.user.delete('secret')
ok

Delete an existing user.

Required parameters

Parameter Description
token String The user’s token.
current_password String The user’s current password.

Optional parameters

Parameter Description
reason_for_delete String A reason for deletion, that is used for sending feedback back to Todoist.

Update user’s properties

An example of updating the user’s properties:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "user_update", "uuid": "52f83009-7e27-4b9f-9943-1c5e3d1e6889", "args": {"time_format": 0}}]'
{ ...
  "sync_status": {"52f83009-7e27-4b9f-9943-1c5e3d1e6889": "ok"},
  ... }

>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.user.update(time_format=0)

Update the details of the user.

Optional parameters

Parameter Description
email String The user’s email.
full_name String The user’s real name formatted as Firstname Lastname.
password String The user’s password.
timezone String The user’s timezone (a string value such as UTC, Europe/Lisbon, US/Eastern, Asian/Taipei).
start_page String The user’s default view on Todoist. The start page can be one of the following: _info_page for the info page, _blank for a blank page, _project_<PROJECT_ID> for project with id <PROJECT_ID>, and <ANY_QUERY> to query after anything.
start_day Integer The first day of the week (between 1 and 7, where 1 is Monday and 7 is Sunday).
next_week Integer The day of the next week, that tasks will be postponed to (between 1 and 7, where 1 is Monday and 7 is Sunday).
time_format Integer Whether to use a 24h format such as 13:00 (if set to 0) when displaying time, or a 12h format such as 1:00pm (if set to 1).
date_format Integer Whether to use the DD-MM-YYYY date format (if set to 0), or the MM-DD-YYYY format (if set to 1).
sort_order Integer Whether to show projects in an oldest dates first order (if set to 0, or a oldest dates last order (if set to 1).
default_reminder String The default reminder for the user. Reminders are only possible for Premium users. The default reminder can be one of the following: email to send reminders by email, mobile to send reminders to mobile devices via SMS, push to send reminders to smart devices using push notifications (one of the Android or iOS official clients must be installed on the client side to receive these notifications), no_default to turn off sending default reminders.
auto_reminder Integer The default time in minutes for the automatic reminders set, whenever a due date has been specified for a task.
mobile_number String The user’s mobile number (null if not set).
mobile_host String The user’s mobile host (or null if not set).
theme Integer The currently selected Todoist theme (between 0 and 10).

Update karma goals

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "update_goals", "uuid": "b9bbeaf8-9db6-452a-a843-a192f1542892", "args": {"vacation_mode": 1}}]'
{ ...
  "sync_status": {"b9bbeaf8-9db6-452a-a843-a192f1542892": "ok"},
  ... }

>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.user.update_goals(vacation_mode=1)

Update the karma goals of the user.

Optional parameters

Parameter Description
daily_goal Integer The target number of tasks to complete per day.
weekly_goal Integer The target number of tasks to complete per week.
ignore_days Integer A list with the days of the week to ignore (1 for Monday and 7 for Sunday).
vacation_mode Integer Marks the user as being on vacation (where 1 is true and 0 is false).
karma_disabled Integer Whether to disable the karma and goals measuring altogether (where 1 is true and 0 is false).

Update notification settings

An example of updating the user’s notification settings

$ curl https://todoist.com/API/v7/notification_settings/update \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d notification_type=item_completed \
    -d service=email \
    -d dont_notify=1
{
  "user_left_project": {
    "notify_push": true,
    "notify_email": true
  },
  "biz_trial_will_end": {
    "notify_push": true,
    "notify_email": true
  },
  "biz_trial_enter_cc": {
    "notify_push": true,
    "notify_email": true
  },
  "item_completed": {
    "notify_push": true,
    "notify_email": false
  },
  "share_invitation_rejected": {
    "notify_push": true,
    "notify_email": true
  },
  "note_added": {
    "notify_push": true,
    "notify_email": true
  },
  "biz_account_disabled": {
    "notify_push": true,
    "notify_email": true
  },
  "biz_invitation_rejected": {
    "notify_push": true,
    "notify_email": true
  },
  "item_uncompleted": {
    "notify_push": true,
    "notify_email": true
  },
  "item_assigned": {
    "notify_push": true,
    "notify_email": true
  },
  "share_invitation_accepted": {
    "notify_push": true,
    "notify_email": true
  },
  "user_removed_from_project": {
    "notify_push": true,
    "notify_email": true
  },
  "biz_invitation_accepted": {
    "notify_push": true,
    "notify_email": true
  },
  "biz_payment_failed": {
    "notify_push": true,
    "notify_email": true
  }
}
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.user.update_notification_setting('item_completed', 'email', 1)
{
  'biz_invitation_rejected': {
    'notify_push': True,
    'notify_email': True
  },
  'user_left_project': {
    'notify_push': True,
    'notify_email': True
  },
  'note_added': {
    'notify_push': True,
    'notify_email': True
  },
  'biz_trial_enter_cc': {
    'notify_push': True,
    'notify_email': True
  },
  'item_completed': {
    'notify_push': True,
    'notify_email': False
  },
  'biz_trial_will_end': {
    'notify_push': True,
    'notify_email': True
  },
  'biz_account_disabled': {
    'notify_push': True,
    'notify_email': True
  },
  'share_invitation_rejected': {
    'notify_push': True,
    'notify_email': True
  },
  'item_uncompleted': {
    'notify_push': True,
    'notify_email': True
  },
  'item_assigned': {
    'notify_push': True,
    'notify_email': True
  },
  'share_invitation_accepted': {
    'notify_push': True,
    'notify_email': True
  },
  'user_removed_from_project': {
    'notify_push': True,
    'notify_email': True
  },
  'biz_invitation_accepted': {
    'notify_push': True,
    'notify_email': True
  },
  'biz_payment_failed': {
    'notify_push': True,
    'notify_email': True
  }
}

Update the user’s notification settings.

Required parameters

Parameter Description
token String The user’s token received on login.
notification_type String The notification type. For a list of notifications have a look at the Live Notifications section.
service String The service type, which can take the values: email or push.
dont_notify Integer Whether notifications of this service should be notified (1 to not notify, and 0 to nofify).

Sharing

Project can be shared with other users, which are then called collaborators, and this section describes the different commands that are related to sharing.

Collaborators

An example of a collaborator object:

{
  "id": 1855589,
  "email": "you@example.com",
  "full_name": "Example User",
  "timezone": "GMT +3:00",
  "image_id": null
}

There are two types of objects to get information about a user’s collaborators and their participation in shared projects: collaborators and collaborator_states

Every user who shares at least one project with a user, has a collaborators record in the API response. The record contains a restricted subset of user-specific properties.

Property Description
id Integer The user id of the collaborator.
email String The email of the collaborator.
full_name String The full name of the collaborator.
timezone String The timezone of the collaborator.
image_id Integer The image id for the collaborator’s avatar, which can be used to get an avatar from a specific URL. Specifically the https://dcff1xvirvpfp.cloudfront.net/<image_id>_big.jpg can be used for a big (195x195 pixels) avatar, https://dcff1xvirvpfp.cloudfront.net/<image_id>_medium.jpg for a medium (60x60 pixels) avatar, and https://dcff1xvirvpfp.cloudfront.net/<image_id>_small.jpg for a small (35x35 pixels) avatar.

Partial sync returns updated collaborator objects for users that have changed their attributes, such as their name or email.

Collaborator states

An example of a collaborator state:

{
  "project_id": 128501470,
  "user_id": 1855589,
  "state": "active",
  "is_deleted": false
}

The list of collaborators doesn’t contain any information on how users are connected to shared projects. To provide information about these connections, the collaborator_states field should be used. Every collaborator state record is a mere “user to shared project” mapping.

Property Description
project_id Integer The shared project id of the user.
user_id Integer The user id of the collaborator.
state String The status of the collaborator state, either active or deleted (when the collaborator left the shared project).
is_deleted Boolean Set to true when the collaborator leaves the shared project.

Share a project

An example of sharing a project:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "share_project", "temp_id": "854be9cd-965f-4ddd-a07e-6a1d4a6e6f7a", "uuid": "fe6637e3-03ce-4236-a202-8b28de2c8372", "args": {"project_id": "128501470", "email": "you@example.com"}}]'
{ ...
  "sync_status": {"fe6637e3-03ce-4236-a202-8b28de2c8372": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.projects.share(128501470, 'you@example.com')
>>> api.commit()

Share a project.

Required arguments

Argument Description
project_id Integer or String (temp_id) The project to be shared.
email String The user email with whom to share the project.

Delete a collaborator

An example of deleting a person from a shared project:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "delete_collaborator", "uuid": "0ae55ac0-3b8d-4835-b7c3-59ba30e73ae4", "args": {"project_id": 128501470, "email": "you@example.com"}}]'
{ ...
  "sync_status": {"0ae55ac0-3b8d-4835-b7c3-59ba30e73ae4": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.collaborators.delete(128501470, 'you@example.com')
>>> api.commit()

Delete a person from a shared project.

Required arguments

Argument Description
project_id Integer or String (temp_id) The project to be affected.
email String The user email with whom the project was shared with.

Accept an invitation

An example of accepting an invitation:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "accept_invitation", "uuid": "4b254da4-fa2b-4a88-9439-b27903a90f7f", "args": {"invitation_id": 1234,  "invitation_secret": "abcdefghijklmno"}}]'
{ ...
  "sync_status": {"4b254da4-fa2b-4a88-9439-b27903a90f7f": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.invitations.accept(1234, 'abcdefghijklmno')
>>> api.commit()

Accept an invitation.

Required arguments

Argument Description
invitation_id Integer The invitation id.
invitation_secret String The secret fetched from the live notification.

Reject an invitation

An example of rejecting an invitation:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "reject_invitation", "uuid": "284fd900-c36f-44e5-ab92-ee93455e50e0", "args": {"invitation_id": 1234,  "invitation_secret": "abcdefghijklmno"}}]'
{ ...
  "sync_status": {"284fd900-c36f-44e5-ab92-ee93455e50e0": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.invitations.reject(1234, 'abcdefghijklmno')
>>> api.commit()

Reject an invitation.

Required arguments

Argument Description
invitation_id Integer The invitation id.
invitation_secret String The secret fetched from the live notification.

Delete an invitation

An example of deleting an invitation:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "delete_invitation", "uuid": "399f6a8d-ddea-4146-ae8e-b41fb8ff6945", "args": {"invitation_id": 128501470}}]'
{ ...
  "sync_status": {"399f6a8d-ddea-4146-ae8e-b41fb8ff6945": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.invitations.delete(128501470)
>>> api.commit()

Delete an invitation.

Required arguments

Argument Description
invitation_id Integer The invitation to be deleted.

Live notifications

Examples of live notifications:

{
    "created": 1377639720,
    "from_uid": 123,
    "id": 1,
    "invitation_id": 456,
    "invitation_secret": "abcdefghijklmno",
    "notification_key": "notification_123",
    "notification_type": "share_invitation_sent",
    "seq_no": 12345567890,
    "state": "accepted"
}

{
    "created": 1377639720,
    "from_uid": 123,
    "id": 2,
    "invitation_id": 456,
    "notification_key": "notification_123",
    "notification_type": "share_invitation_accepted",
    "project_id": 789,
    "seq_no": 1234567890
}

{
    "created": 1377639720,
    "from_uid": 123,
    "id": 3,
    "invitation_id": 456,
    "notification_key": "notification_123",
    "notification_type": "share_invitation_rejected",
    "project_id": 789,
    "reject_email": "me@example.com",
    "seq_no": 1234567890
}

{
    "created": 1377639720,
    "from_uid": 123,
    "id": 4,
    "notification_key": "notification_123",
    "notification_type": "user_left_project",
    "project_id": 456,
    "seq_no": 1234567890
}

{
    "created": 1377639720,
    "from_uid": 123,
    "id": 5,
    "notification_key": "notification_123",
    "notification_type": "user_removed_from_project",
    "project_id": 456,
    "removed_name": "Example User",
    "removed_uid": 789,
    "seq_no": 1234567890
}

{
    "assigned_by_uid": 789,
    "created": 1377639720,
    "from_uid": 123,
    "id": 6,
    "item_content": "NewTask",
    "item_id": 456,
    "notification_key": "notification_123",
    "notification_type": "item_assigned",
    "project_id": 789,
    "responsible_uid": 321,
    "seq_no": 1234567890
}

{
    "assigned_by_uid": 789,
    "created": 1377639720,
    "from_uid": 123,
    "id": 7,
    "item_content": "NewTask",
    "item_id": 456,
    "notification_key": "notification_123",
    "notification_type": "item_completed",
    "project_id": 789,
    "responsible_uid": 321,
    "seq_no": 1234567890
}

{
    "assigned_by_uid": 789,
    "created": 1377639720,
    "from_uid": 123,
    "id": 8,
    "item": 456,
    "item_content": "NewTask",
    "notification_key": "notification_123",
    "notification_type": "item_uncompleted",
    "project": 789,
    "responsible_uid": 321,
    "seq_no": 1234567890
}

{
    "created": 1377639720,
    "from_uid": 123,
    "id": 9,
    "item_id": 456,
    "note_content": "NewTask",
    "note_id": 789,
    "notification_key": "notification_123",
    "notification_type": "note_added",
    "project_id": 321,
    "seq_no": 1234567890
}

{
    "created": 1377639720,
    "email": "me@example.com",
    "from_uid": 123,
    "id": 10,
    "notification_key": "notification_123",
    "notification_type": "biz_policy_disallowed_invitation",
    "project_id": 456,
    "seq_no": 1234567890,
    "from_user": {
        "email": "you@example.com",
        "full_name": "Example User",
        "id": "789",
        "image_id": "321"
    }
}

{
    "created": 1377639720,
    "from_uid": 123,
    "id": 11,
    "inviter_id": 456,
    "notification_key": "notification_123",
    "notification_type": "biz_policy_rejected_invitation",
    "seq_no": 1234567890,
    "from_user": {
        "email": "you@example.com",
        "full_name": "Example User",
        "id": "789",
        "image_id": "321"
    }
}

{
    "active_until": 1399299727,
    "created": 1377639720,
    "from_uid": 123,
    "id": 12,
    "notification_key": "notification_123",
    "notification_type": "biz_trial_will_end",
    "plan": "business_monthly",
    "quantity": 10,
    "seq_no": 1234567890
}

{
    "active_until": 1399299727,
    "amount_due": 600,
    "attempt_count": 1,
    "created": 1377639720,
    "currency": "usd",
    "description": "2 x Subscription to Monthly ($3.00/month)",
    "from_uid": 123,
    "id": 13,
    "next_payment_attempt": 1399299735,
    "notification_key": "notification_123",
    "notification_type": "biz_payment_failed",
    "plan": "business_monthly",
    "quantity": 10,
    "seq_no": 1234567890
}

{
    "active_until": 1399299727,
    "created": 1377639720,
    "from_uid": 123,
    "id": 14,
    "notification_key": "notification_123",
    "notification_type": "biz_account_disabled",
    "plan": "business_monthly",
    "quantity": 10,
    "seq_no": 1234567890
}

{
    "account_name": "Example Inc.",
    "created": 1377639720,
    "from_uid": 123,
    "from_user": {
        "email": "you@example.com",
        "full_name": "Example User",
        "id": "456",
        "image_id": "789"
    },
    "id": 15,
    "invitation_id": 321,
    "invitation_message": "Welcome to our team!",
    "invitation_secret": "abcdefghijklmno",
    "notification_key": "notification_123",
    "notification_type": "biz_invitation_created",
    "seq_no": 1234567890,
    "state": "accepted"
}

{
    "created": 1377639720,
    "from_uid": 123,
    "from_user": {
        "account_name": "Example Inc.",
        "email": "you@example.com",
        "full_name": "Example User",
        "id": "456",
        "image_id": "789"
    },
    "id": 16,
    "invitation_id": 321,
    "notification_key": "notification_123",
    "notification_type": "biz_invitation_accepted",
    "seq_no": 1234567890
}

{
    "created": 1377639720,
    "from_uid": 123,
    "from_user": {
        "account_name": "Example Inc.",
        "email": "you@example.com",
        "full_name": "Example User",
        "id": "456",
        "image_id": "789"
    },
    "id": 17,
    "invitation_id": 321,
    "notification_key": "notification_123",
    "notification_type": "biz_invitation_rejected",
    "seq_no": 1234567890
}

Types

This is the list of notifications which can be issued by the system:

Type Description
share_invitation_sent Sent to the sharing invitation receiver.
share_invitation_accepted Sent to the sharing invitation sender, when the receiver accepts the invitation.
share_invitation_rejected Sent to the sharing invitation sender, when the receiver rejects the invitation.
user_left_project Sent to everyone when somebody leaves the project.
user_removed_from_project Sent to everyone, when a person removes somebody from the project.
item_assigned Sent to user who is responsible for the task. Optionally it’s also sent to the user who created the task initially, if the assigner and the task creator is not the same person.
item_completed Sent to the user who assigned the task when the task is completed. Optionally it’s also sent to the user who is responsible for this task, if the responsible user and the user who completed the task is not the same person.
item_uncompleted Sent to the user who assigned the task when the task is uncompleted. Optionally it’s also sent to the user who is responsible for this task, if the responsible user and the user who completed the task is not the same person.
note_added Sent to all members of the shared project, whenever someone adds a note to the task.
biz_policy_disallowed_invitation Sent to you when you try to share a project with someone outside of your business account, but the business account policy disallows this action.
biz_policy_rejected_invitation Sent to you when you try to accept the invitation to a shared project from someone outside of your business account, but the business account policy disallows this action.
biz_trial_will_end Sent to all business account administrators three days before the trial period of a subscription is scheduled to end.
biz_payment_failed Sent to all business account administrators whenever an invoice attempt payment fails. This can occur either due to a declined payment, or because the customer has no active card. A particular case of note is that if a customer with no active card reaches the end of its free trial.
biz_account_disabled Sent to all business account administrators when the account is disabled.
biz_invitation_created Sent to an invitee, when one of business account administrators invites this user to the business account.
biz_invitation_accepted Sent to an inviter, when the invitation is accepted.
biz_invitation_rejected Sent to an inviter, when the invitation is rejected.

Common properties

Some properties are common for all types of notifications, whereas some others depend on the notification type.

Every live notification has the following properties:

Property Description
id Integer The id of the live notification.
created Integer Live notification creation date. A number representing a timestamp since epoch.
from_uid Integer The id of the user who initiated this live notification.
notification_key String Unique notification key.
notification_type String Type of notification. Different notification type define different extra fields which are described below.
seq_no Integer Notification sequence number.

Specific properties

Here are the extra properties for the *_invitation_* types of live notifications:

Property Description
from_user Object User data, useful on share_invitation_sent.
project_name String The project name, useful for share_invitation_* where you may not have the project in the local model.
invitation_id Integer The invitation id. Useful for accepting/rejecting invitations.
invitation_secret String The invitation secret key. Useful for accepting/rejecting invitations.

Here are the extra properties for the share_invitation_sent type of live notifications:

Property Description
state String Invitation state. Initially invited, can change the state to accepted or rejected.

Here are the extra properties for the user_removed_from_project type of live notifications:

Property Description
removed_name String The name of the user removed.
removed_uid Integer The uid of the user removed.

Here are the extra properties for the biz_trial_will_end type of live notifications:

Property Description
quantity Integer The number of users under the control of the business account.
plan Tariff plan name. Valid values are business_monthly and business_yearly.
active_until Integer The timestamp when the business account will be disabled. The value may not match the business account subscription end date, as we give some extra days (up to two weeks) to pay the invoice.

Here are the extra properties for the biz_payment_failed type of live notifications:

Property Description
quantity Integer The number of users under the control of the business account.
plan String Tariff plan name. Valid values are business_monthly and business_yearly.
active_until Integer The timestamp when the business account will be disabled. The value may not match the business account subscription end date, as we give some extra days (up to two weeks) to pay the invoice.
amount_due Integer Invoice amount. Integer value in 0.01 of currency.
attempt_count Integer Number of automatic payment attempts made for this invoice.
currency String Currency value. Three-letter ISO currency code representing the currency in which the charge was made.
description String Invoice description.
next_payment_attempt String Timestamp value.

Here are the extra properties for the biz_account_disabled type of live notifications:

Property Description
quantity Integer The number of users under the control of the business account.
plan String Tariff plan name. Valid values are business_monthly and business_yearly.
active_until Integer The timestamp when the business account will be disabled. The value may not match the business account subscription end date, as we give some extra days (up to two weeks) to pay the invoice.

Here are the extra properties for the biz_invitation_created type of live notifications:

Property Description
state String Invitation state. Initially invited, can change the state to accepted or rejected.
invitation_secret String Invitation secret. Should be used to accept or reject invitation.
invitation_message String Invitation message.
account_name String Business account (company) name.

Mark last read

An example of marking the last read notification:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "live_notifications_set_last_read", "uuid": "588b9ccf-29c0-4837-8bbc-fc858c0c6df8", "args": {"id": 1234}}]'
{ ...
  "sync_status": {"588b9ccf-29c0-4837-8bbc-fc858c0c6df8": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.live_notifications.set_last_read(1234)
>>> api.commit()

Mark the last read live notification.

Required arguments

Argument Description
id The id of the last read notification (a number or 0 or null to mark all read).

Business

An example invitation object:

{
  "base_url": "http://todoist.com",
  "business_account_id": 2,
  "email": "z@example.com",
  "id": 13,
  "inviter_id": 1,
  "message": "Welcome to our company business account",
  "secret": "0692805f97d9c091debaba52d18f5696",
  "user_id": 1
}

The set of functions and Sync API commands to manage Todoist Business accounts. All these functionality is only available for Business account admins.

In order to become a business account admin, you should create a new account from Todoist Business Free Trial, or to ask another business account admin to invite you, and to make you an admin.

User, who is also a business account admin has the attribute is_biz_admin, set to true.

Send invitation

An example of sending an invitation:

$ curl https://todoist.com/API/v7/business/users/invite \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d email_list='["spam@example.com","egg@example.com"]'
    -d message='Welcome'
[
  {
    "base_url": "http://todoist.com",
    "business_account_id": 2,
    "email": "spam@example.com",
    "id": 15,
    "inviter_id": 1,
    "message": "Welcome",
    "secret": "21d5a7fc4fa7e9d47a6642069d2af6ef",
    "user_id": 6
  },
  {
    "base_url": "http://todoist.com",
    "business_account_id": 2,
    "email": "egg@example.com",
    "id": 16,
    "inviter_id": 1,
    "message": "Welcome",
    "secret": "4e20a8b58abe07441c4c30fff34798ed",
    "user_id": 15
  }
]
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.business_users.invite(['spam@example.com','egg@example.com'])
[
  {
    'base_url': 'http://todoist.com',
    'business_account_id': 2,
    'email': 'spam@example.com',
    'id': 15,
    'inviter_id': 1,
    'message': 'Welcome',
    'secret': '21d5a7fc4fa7e9d47a6642069d2af6ef',
    'user_id': 6
  },
  {
    'base_url': 'http://todoist.com',
    'business_account_id': 2,
    'email': 'egg@example.com',
    'id': 16,
    'inviter_id': 1,
    'message': 'Welcome',
    'secret': '4e20a8b58abe07441c4c30fff34798ed',
    'user_id': 15
  }
]

This function allows you to send invitation to your business account. Every invitation object has unique id and secret code. Anyone who knows this information, can activate invitation and join your business account. Invitation is deactivated at the moment it’s accepted or rejected by receiver, or deleted manually by sender.

Invitation objects are not created (quietly skipped), if the invitation recipient is an existing Todoist user and this user already belongs to a business account.

If an invitation for that recipient already exists and hasn’t been activated yet, a new invitation object will not be created. Instead, an existing invitation will be re-sent and the corresponding invitation object will be returned back.

The return value is a list of invitation objects.

Required arguments

Argument Description
token String User’s access token
email_list List of Strings The emails of users which will be invited

Optional arguments

Argument Description
message String Additional text which will be included to invitation welcome message

Accept invitation

An example of accepting a business invitation with a direct call:

$ curl https://todoist.com/API/v7/business/users/accept_invitation \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d id=1234 \
    -d secret=abcdefghijklmno
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.business_users.accept_invitation(1234, 'abcdefghijklmno')

An example of accepting a business invitation with a Sync API command:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "biz_accept_invitation", "uuid": "48538e47-7a9f-4f3d-927a-463ea997675e", "args": {"invitation_id": 1234,  "invitation_secret": "abcdefghijklmno"}}]'
{ ...
  "sync_status": {"48538e47-7a9f-4f3d-927a-463ea997675e": "ok"},
  ... }
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.biz_invitations.accept(1234, 'abcdefghijklmno')
>>> api.commit()

Accept an invitation from Todoist for Business. There are currently 2 ways to accept an invitation, either with a direct call, or by using a Sync API command, as can be seen from the examples on the side, and the different required arguments below.

The invitation is accepted if it’s still active and user doesn’t belong to any business account yet. For the direct call, null denotes a successful return value.

Required arguments

For the direct call:

Argument Description
token String User’s access token
id Integer The invitation id (a number).
secret String The secret fetched from the live notification (a string value).

For the Sync API command:

Argument Description
invitation_id Integer The invitation id (a number).
invitation_secret String The secret fetched from the live notification (a string value).

Reject invitation

An example of rejecting a business invitation with a direct call:

$ curl https://todoist.com/API/v7/business/users/reject_invitation \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d id=1234 \
    -d secret=abcdefghijklmno
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.business_users.reject_invitation(1234, 'abcdefghijklmno')

An example of rejecting a business invitation with a Sync API command:

$ curl https://todoist.com/API/v7/sync \
    -d token=0123456789abcdef0123456789abcdef01234567 \
    -d commands='[{"type": "biz_reject_invitation", "uuid": "a1b0460a-aab3-4555-9109-779cd0cb0966", "args": {"invitation_id": 1234,  "invitation_secret": "abcdefghijklmno"}}]'
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.biz_invitations.reject(1234, 'abcdefghijklmno')
>>> api.commit()

Reject an invitation from Todoist for Business. There are currently 2 ways to reject an invitation, either with a direct call, or by using a Sync API command, as can be seen from the examples on the side, and the different required arguments below.

The invitation is rejected and deleted. Note that the client doesn’t have to provide the user’s token to reject invitation: it’s enough to provide knowledge of invitation secret business account yet. For the direct call, null denotes a successful return value.

Required arguments

For the direct call:

Argument Description
id Integer The invitation id (a number).
secret String The secret fetched from the live notification (a string value).

For the Sync API command:

Argument Description
invitation_id Integer The invitation id (a number).
invitation_secret String The secret fetched from the live notification (a string value).

Optional arguments

For the direct call:

Argument Description
token String User’s access token

Activity

The activity log makes it easy to see everything that is happening across projects, items and notes.

Note that, the activity log is only available for Todoist Premium.

Logged events

Currently the official Todoist clients present only the most important events that most users are interested in, but actually everything that has to do with projects, items and notes, is stored in our DB, and can be accessed by using our API.

The following events are logged for items:

  • items added
  • items updated (only changes to content, due_data and responsible_uid)
  • items deleted
  • items completed
  • items uncompleted

The following events are logged for notes:

  • notes added
  • notes updated (only changes to content or file_name if the former is empty)
  • notes deleted

The following events are logged for projects:

  • projects added
  • projects updated (only changes to name)
  • projects deleted
  • projects archived
  • projects unarchived
  • projects shared
  • projects left

Event properties

An example of an activity log event:

{
  "id" : 955333384,
  "object_type" : "item",
  "object_id" : 101157918,
  "event_type" : "added",
  "event_date" : "Fri 01 Jul 2016 14:24:59 +0000",
  "parent_project_id" : 174361513,
  "parent_item_id" : null,
  "initiator_id" : null,
  "extra_data" : {
    "content" : "Task1"
  }
}
{
  'id': 955333384,
  'object_type': 'item',
  'object_id': 101157918,
  'event_type': 'added',
  'event_date': 'Fri 01 Jul 2016 14:24:59 +0000',
  'parent_project_id': 174361513,
  'parent_item_id': None,
  'initiator_id': None,
  'extra_data': {
    'content': 'Task1'
  }
}
Property Description
id Integer The id of the event.
object_type String The type of object, one of item, note or project.
object_id Integer The id of the object.
event_type String The type of event, one of added, updated, deleted, completed, uncompleted, archived, unarchived, shared, left.
event_date String The date and time when the event took place.
parent_project_id Integer The id of the item’s or note’s parent project, otherwise null.
parent_item_id Integer The id of the note’s parent item, otherwise null.
initiator_id Integer The id of the user who is responsible for the event, which only makes sense in shared projects, items and notes, and is null for non-shared objects.
extra_data Object This object contains at least the name of the project, or the content of an item or note, and optionally the last_name if a projects was renamed, the last_content if an item or note was renamed, the due_date and last_due_date if an item’s due date changed, the responsible_uid and last_responsible_uid if an item’s responsible uid changed.

Get activity logs

An example of getting the activity logs:

$ curl https://todoist.com/API/v7/activity/get \
    -d token=0123456789abcdef0123456789abcdef01234567 \
[
  {
    "id" : 955344370,
    "object_type" : "item",
    "object_id" : 101157918,
    "event_type" : "updated",
    "event_date" : "Fri 01 Jul 2016 14:28:37 +0000",
    "parent_project_id" : 174361513,
    "parent_item_id" : null,
    "initiator_id" : null,
    "extra_data" : {
      "last_due_date" : null,
      "due_date" : "Sat 02 Jul 2016 20:59:59 +0000",
      "content" : "Task1"
    }
  },
  {
    "id" : 955333751,
    "object_type" : "note",
    "object_id" : 23685068,
    "event_type" : "added",
    "event_date" : "Fri 01 Jul 2016 14:25:04 +0000",
    "parent_project_id" : 174361513,
    "parent_item_id" : 101157918,
    "initiator_id" : null,
    "extra_data" : {
      "content" : "Note1"
    }
  },
  {
    "id" : 955333384,
    "object_type" : "item",
    "object_id" : 101157918,
    "event_type" : "added",
    "event_date" : "Fri 01 Jul 2016 14:24:59 +0000",
    "parent_project_id" : 174361513,
    "parent_item_id" : null,
    "initiator_id" : null,
    "extra_data" : {
      "content" : "Task1"
    }
  },
  {
    "id" : 955333239,
    "object_type" : "project",
    "object_id" : 174361513,
    "event_type" : "added",
    "event_date" : "Fri 01 Jul 2016 14:24:56 +0000",
    "parent_project_id" : null,
    "parent_item_id" : null,
    "initiator_id" : null,
    "extra_data" : {
      "name" : "Project1"
    }
  }
]
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.activity.get()
[
  {
    'id': 955344370,
    'object_type': 'item',
    'object_id': 101157918,
    'event_type': 'updated',
    'event_date': 'Fri 01 Jul 2016 14:28:37 +0000',
    'parent_project_id': 174361513,
    'parent_item_id': None,
    'initiator_id': None,
    'extra_data': {
      'content': 'Task1',
      'due_date': 'Sat 02 Jul 2016 20:59:59 +0000',
      'last_due_date': None
    }
  },
  {
    'id': 955333751,
    'object_type': 'note',
    'object_id': 23685068,
    'event_type': 'added',
    'event_date': 'Fri 01 Jul 2016 14:25:04 +0000',
    'parent_project_id': 174361513,
    'parent_item_id': 101157918,
    'initiator_id': None,
    'extra_data': {
      'content': 'Note1'
    }
  },
  {
    'id': 955333384,
    'object_type': 'item',
    'object_id': 101157918,
    'event_type': 'added',
    'event_date': 'Fri 01 Jul 2016 14:24:59 +0000',
    'parent_project_id': 174361513,
    'parent_item_id': None,
    'initiator_id': None,
    'extra_data': {
      'content': 'Task1'
    }
  },
  {
    'id': 955333239,
    'object_type': 'project',
    'object_id': 174361513,
    'event_type': 'added',
    'event_date': 'Fri 01 Jul 2016 14:24:56 +0000',
    'parent_project_id': None,
    'parent_item_id': None,
    'initiator_id': None,
    'extra_data': {
      'name': 'Project1'
    }
  }
]

Required parameters

Parameter Description
token String The user’s token received on login (a string hash value).

Optional parameters

Parameter Description
object_type String Filters events by a specific object type.
object_id Integer Filters events by a specific object id, but only if the object_type has been also specified.
event_type String Filters events by a specific event type.
object_event_types Array of Strings An alternative way to filter by multiple object and event types. This takes a list of strings of the form [object_type]:[event_type] (where either object_type part or the event_type part can be ommited), such as for example ["item:", "note:added"]. When this parameter is specified the object_type, event_type and object_id parameters are ignored.
parent_project_id Integer Filters object events by the id of the project they belong to, so this implicitly limits the results to items and notes.
parent_item_id Integer Filters object events by the id of the item they belong, so this implicitly limits the results to notes.
initiator_id Integer Filters event by the id of the initiator.
since String Filters events to those that took place after the specified date and time, formatted as for example 2016-06-28T12:00.
until String Filters events to those that took place before the specified date and time, formatted as 2016-06-28T12:00.
limit Integer The number of events to return, where the default is 30, and the maximum is 100.
offset Integer The number of events to skip, which can be used for pagination in order to get more events than those returned by the previous call.

Backups

Get backups

Todoist creates a backup archive of users' data on a daily basis. Backup archives can also be accessed from the web app (Todoist Settings -> Backups).

The list of recent backup archives can be accessed via the following API endpoint, and upon successful request, a HTTP 200 response will be returned with a list of backup archives in JSON format:

$ curl https://todoist.com/API/v7/backups/get \
    -d token=0123456789abcdef0123456789abcdef01234567
[
  {
    "version": "2016-01-13 02:03",
    "url": "https://s3.amazonaws.com/user_backups.todoist.com/..."
  },
    ...
]
>>> import todoist
>>> api = todoist.TodoistAPI('0123456789abcdef0123456789abcdef01234567')
>>> api.backups.get()
[
  {
    'version': '2016-01-13 02:03',
    'url': 'https://s3.amazonaws.com/user_backups.todoist.com/...'
  },
  ...
]

Required parameters

Parameter Description
token String The user’s token received on login (a string hash value).

URL schemes

The following URL schemes might also be useful when accessing the Todoist applications (iOS and Android) or when performing certain actions with them, so they are also included here for completeness.

Views

The following schemes are available to open a specific view:

Scheme Description
todoist:// Opens Todoist.
todoist://today Opens the today view.
todoist://next7days Opens the next 7 days view.
todoist://profile Opens the profile view.
todoist://inbox Opens the inbox view.
todoist://teaminbox Opens the team inbox view. If the user doesn’t have a business account (access to team inbox), it will show an alert saying that he/she doesn’t have access to the team inbox because he/she doesn’t have a business account and will be redirected automatically to the inbox view.
todoist://notifications Opens notifications view.

Tasks

Example of adding a task:

todoist://addtask?content=mytask&date=tomorrow&priority=4

The following scheme is available to create new tasks:

Scheme Description
todoist://addtask Opens the add task view to add a new task to Todoist.

Here’s an example of a content value:

Create document about URL Schemes!

And how it should be supplied using Percent-encoding:

Create&20document%20about%20URL%20Schemes%21

Here’s an example of a date value:

Tomorrow @ 14:00

And how it should be supplied using Percent-encoding:

Tomorrow%20@%2014:00

The todoist://addtask scheme accepts the following optional values:

Value Description
content The content of the task, which should be a string that in Percent-encoding (also known as URL encoding).
date The due date of the task, which should be a string that in Percent-encoding (also known as URL encoding). Look at our reference to see which formats are supported.
priority The priority of the task, which should be a string with a value from 1 to 4.

If all the values are empty, it will just open the add task view. This URL Scheme will not automatically add the task to Todoist, it will just open the add task view and fill the fields.

Projects

The following scheme is available to show all the projects:

Scheme Description
todoist://projects Opens the projects view (shows all projects).

Example of opening a specific project:

todoist://project?id=128501470

The following scheme is available to open a specific project:

Scheme Description
todoist://project Opens a specific project using the id of the project.

The todoist://project scheme accepts the following required value:

Value Description
id The id of the project to view. If the id doesn’t exist, you don’t have access to the project, or the value is empty, an alert will be showed and the user will be redirected to the projects view.

Labels

The following scheme is available to show all the labels:

Scheme Description
todoist://labels Opens the labels view (shows all labels)

Example of opening a specific label:

todoist://label?id=1234

The following scheme is available to open a specific label:

Scheme Description
todoist://label Opens a specific label using the id of the label.

The todoist://label scheme accepts the following required value:

Value Description
id The id of the label to view. If the id doesn’t exist, you don’t have access to the label, or the value is empty, an alert will be showed and the user will be redirected to the labels view.

Filters

The following scheme is available to show all the filters:

Scheme Description
todoist://filters Opens the filters view (shows all filters)

Example of opening a specific filter:

todoist://filter?id=9

The following scheme is available to open a specific filter:

Scheme Description
todoist://filter Opens a specific filter using the id of the filter.

The todoist://filter scheme accepts the following required value:

Value Description
id The id of the filter to view. If the id doesn’t exist, you don’t have access to the filter, or the value is empty, an alert will be showed and the user will be redirected to the filters view.

Example of searching for “Test & Today”:

todoist://search?query=Test%20%26%20Today

The following scheme is available for searching (Android only):

Scheme Description
todoist://search Used to search in the Todoist application.

The todoist://search scheme accepts the following required value:

Value Description
query The query to search in the Todoist application, which should be a string that is in Percent-encoding (also known as URL encoding).

Webhooks

The Todoist Webhooks API allows applications to receive real-time notification (in the form of HTTP POST payload) on the subscribed user events. Notice that once you have a webhook setup, you will start receiving webhook events from all your app users immediately.

Important Considerations

Due to the nature of network requests, your application should assume webhook requests could arrive out of order or could even fail to arrive; webhooks should be used only as notifications and not as a primary Todoist data source (make sure your application could still work when webhook is not available).

Configuration

Before you can start receiving webhook event notifications, you must first have your webhook configured at the App Management Console.

Events

Here is a list of events that you could subscribe to, and they are configured at the App Management Console.

Event Name Description
item:added An item was added
item:updated An item was updated
item:deleted An item was deleted
item:completed An item was completed
item:uncompleted An item was uncompleted
note:added A note was added
note:updated A note was updated
note:deleted A note was deleted
project:added A project was added
project:updated A project was updated
project:deleted A project was deleted
project:archived A project was archived
project:unarchived A project was unarchived
label:added A label was added
label:deleted A label was deleted
label:updated A label was updated
filter:added A filter was added
filter:deleted A filter was deleted
filter:updated A filter was updated
reminder:fired A reminder has fired

Request Format

Event JSON Object

Each webhook event notification request contains a JSON object. The event JSON object follows this general structure:

{"event_name": "...", "user_id"=..., "event_data": {...}}

The structure of the “event_data” object varies depending on the type of event it is. For instance, if it is an “item:added” event notification, The “event_data” will represent the newly added item.

Example Delivery

POST /payload HTTP/1.1

Host: your_callback_url_host
Content-Type: application/json
X-Todoist-Hmac-SHA256: UEEq9si3Vf9yRSrLthbpazbb69kP9+CZQ7fXmVyjhPs=

{
    "event_name": "item:added",
    "user_id": 1234,
    "event_data": {
      "day_order": -1,
      "assigned_by_uid": 1855589,
      "is_archived": 0,
      "labels": [],
      "sync_id": null,
      "in_history": 0,
      "has_notifications": 0,
      "indent": 1,
      "checked": 0,
      "date_added": "Fri 26 Sep 2014 08:25:05 +0000",
      "id": 33511505,
      "content": "Task1",
      "user_id": 1855589,
      "due_date_utc": null,
      "children": null,
      "priority": 1,
      "item_order": 1,
      "is_deleted": 0,
      "responsible_uid": null,
      "project_id": 128501470,
      "collapsed": 0,
      "date_string": ""
    }
}
  ...

Request Header

Header Name Description
User-Agent Will be set to “Todoist-Webhooks”
X-Todoist-Hmac-SHA256 To verify each webhook request was indeed sent by Todoist, an X-Todoist-Hmac-SHA256 header is included; it is a SHA256 Hmac generated using your client_secret as the encryption key and the whole request payload as the message to be encrypted. The resulting Hmac would be encoded in a base64 string.
X-Todoist-Delivery-ID Each webhook event notification has a unique X-Todoist-Delivery-ID. When a notification request failed to be delivered to your endpoint, the request would be re-delivered with the same X-Todoist-Delivery-ID.

Failed Delivery

When an event notification failed to be delivered to your webhook callback URL endpoint (i.e. due to server error, network failure, incorrect response, etc), it would be re-delivered after 15 mins, and each notification would be re-delivered for at most three times.

Your callback endpoint must respond with a HTTP 200 when receiving an event notification request. A response other than HTTP 200 would be considered as failed delivery, and the notification would be delivered again.