Overview
This is the official documentation for Todoist REST API. Our original API, named Sync API, provides an easy way to deal with full and partial syncs, but it's not so simple for individual calls. Our REST API aims to provide developers a simple way to consume the most basic features of Todoist API.
Request and response format
API endpoints accept arguments either as url-encoded values for non-POST
requests or as json-encoded objects encoded in POST request body with a
Content-Type: application/json
header.
POST requests may provide an additional X-Request-Id
HTTP header containing a
unique string to ensure modifications apply only once.
Requests having the same ID as a previously processed request will be discarded.
This is not required but can be useful for implementation of request
retry logic. This header value should not exceed 36 bytes. We will be
generating them with uuidgen
in the shell code examples.
This API relies on standard HTTP response codes to indicate operation result. The table below is a simple reference about the most used status codes:
Status code | Description |
---|---|
200 | The request was processed successfully. |
204 | The request was processed successfully without any data to return. |
4xx | The request was processed with an error. The request was invalid and should not be retried unmodified. |
5xx | The request failed due to a server error, it's safe to retry later. |
All 200 OK
responses have the Content-type: application/json
and contain a
JSON-encoded representation of one or more objects.
Client SDKs
Our Python and JavaScript SDKs simplify working with Todoist data by reducing the complexity of calling the Todoist APIs.
Python SDK
Install the Todoist Python SDK with pip:
pip install todoist-api-python
Note that this SDK differs from our previous Python SDK. The older SDK was using our Sync API and is now deprecated.
View code samples for the Python SDK by switching to the 'Python SDK' tab at the top of the right-hand panel. The getting started section contains some simple examples of setup and usage.
You can find the Python SDK source code at its Github repository.
The todoist-api-python package is distributed via PyPI.
JavaScript SDK
Install the Todoist JavaScript SDK via npm:
npm install @doist/todoist-api-typescript
Note that this SDK includes types for TypeScript.
View code samples for the JavaScript SDK by switching to the 'JavaScript SDK' tab in the right-hand panel. The getting started section contains simple examples of setup and usage.
You can find the JavaScript SDK source code at its Github repository.
The todoist-api-typescript package is distributed via npm.
Getting started
In this section we'll show how to perform some common tasks with the REST API using some simple examples.
We show code samples for each scenario using cURL, the Python SDK, and the JavaScript SDK. Use the tabs at the top of the right-hand panel to switch to the examples for each language.
All the requests in the examples require a user token for authentication. You can find your personal token in the integrations settings view of the Todoist web app and replace the token value in the samples.
Get a user's projects
Sending the request:
$ curl -X GET \
https://api.todoist.com/rest/v1/projects \
-H "Authorization: Bearer 0123456789abcdef0123456789"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
projects = api.get_projects()
print(projects)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getProjects()
.then((projects) => console.log(projects))
.catch((error) => console.log(error))
An example projects response:
[
{
"id": 220474322,
"name": "Inbox",
"comment_count": 10,
"order": 1,
"color": 47,
"shared": false,
"sync_id": 0,
"favorite": false,
"inbox_project": true,
"url": "https://todoist.com/showProject?id=220474322"
}
]
[
Project(
id: 220474322,
name: 'Inbox',
comment_count: 10,
order: 1,
color: 47,
shared: False,
sync_id: 0,
favorite: False,
inbox_project: True,
url: 'https://todoist.com/showProject?id=220474322'
team_inbox: False,
parent_id: None,
)
]
[
{
id: 220474322,
order: 1,
color: 47,
name: 'Inbox',
commentCount: 10,
shared: false,
favorite: false,
url: 'https://todoist.com/showProject?id=220474322',
}
]
First, let's see how we can fetch a list of all the projects in a user's account.
We send a GET
request to the projects
endpoint at https://api.todoist.com/rest/v1/projects
.
With every request to the REST API we pass an authorization header
of type Bearer
with the token for the user account. In the sample the token is set to 0123456789abcdef0123456789
,
you should replace this with your own token.
The API responds with 200
status, and a JSON array containing the user's projects. In this case they have just one project: Inbox
.
We import and construct an instance of TodoistAPI
from the Python SDK.
In the constructor we pass the token for the user account, this token will be used for all subsequent requests using the client instance.
We then call the get_projects
method on the API client, and we are returned a list of Project
items.
In this case the user has just one project: Inbox
.
We import and construct an instance of the TodoistApi
class from the JavaScript SDK.
In the constructor we pass the token for the user account, this token will be used for all subsequent requests using the client instance.
We then call the getProjects
method on the client, and we are returned a list containing each of the user's projects.
In this case the user has just one project: Inbox
.
Adding a new project
Sending the request:
$ curl "https://api.todoist.com/rest/v1/projects" \
-X POST \
--data '{"name": "Shopping List"}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer 0123456789abcdef0123456789"
try:
project = api.add_project(name='Shopping List')
print(project)
except Exception as error:
print(error)
api.addProject({ name: 'Shopping List' })
.then((project) => console.log(project))
.catch((error) => console.log(error))
The response containing the project:
{
"id": 2203306141,
"name": "Shopping List",
"comment_count": 0,
"color": 47,
"shared": false,
"sync_id": 0,
"order": 1,
"favorite": false,
"url": "https://todoist.com/showProject?id=2203306141"
}
Project(
id: 2203306141,
name: 'Shopping List',
comment_count: 0,
order: 1,
color: 47,
shared: False,
sync_id: 0,
favorite: False,
is_inbox_project: False,
is_team_inbox: False,
parent_id: None,
url: 'https://todoist.com/showProject?id=2203306141'
)
{
id: 2203306141,
order: 1,
color: 47,
name: 'Shopping List',
commentCount: 0,
shared: false,
favorite: false,
syncId: 0,
url: 'https://todoist.com/showProject?id=2203306141',
}
Next, let's add a new project to the user's account.
We send a POST
request to the projects
endpoint at https://api.todoist.com/rest/v1/projects
.
As with the previous request, we send the same authorization header containing the user's token.
We'll be sending some JSON data in the body of this request, so we set the Content-Type: application/json
header.
We also generate and send an ID in the X-Request-Id
header. This is optional but can be useful to prevent actions
from being duplicated in the case of retrying failed requests. You can find further details about these headers in the
Request and response format section.
In the body of the request we send a json-encoded object containing the property name
with the value Shopping List
.
Setting the name is mandatory when creating a project, you can find details of the other optional values in the
Projects section.
The API responds with 200
status, and a JSON object containing the data for the project that was added.
Let's make a note of the id
value as we'll use that in the next step.
We already have an instance of the TodoistAPI
client from the previous request, so we'll use this to create a new project.
We call the add_project
method this time, and we pass a name for the new project.
The API client responds with a Project
item containing the data for the new project.
Let's make a note of the id
value as we'll use that in the next step.
We already have an instance of the TodoistApi
client from the previous request, so we'll use this to create a new project.
We call the addProject
method on the client, and we pass an object containing a name for the new project.
The API client responds with an object containing the data for the new project.
Let's make a note of the id
value as we'll use that in the next step.
Adding a new task
Sending the request:
$ curl "https://api.todoist.com/rest/v1/tasks" \
-X POST \
--data '{"content": "Buy Milk", "project_id": 2203306141}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer 0123456789abcdef0123456789"
try:
task = api.add_task(content='Buy Milk', project_id=2203306141)
print(task)
except Exception as error:
print(error)
api.addTask({ content: 'Buy Milk', projectId: 2203306141 })
.then((task) => console.log(task))
.catch((error) => console.log(error))
The response containing the task:
{
"id": 2995104339,
"content": "Buy Milk",
"description": "",
"comment_count": 0,
"completed": false,
"order": 1,
"priority": 1,
"project_id": 2203306141,
"label_ids": [],
"section_id": 0,
"parent_id": 0,
"creator": 2671355,
"created": "2019-12-11T22:36:50.000000Z",
"assigner": null,
"url": "https://todoist.com/showTask?id=2995104339"
}
Task(
id: 2995104339,
content: 'Buy Milk',
description: '',
comment_count: 0,
completed: False,
order: 1,
priority: 1,
project_id: 2203306141,
label_ids: [],
due: None,
section_id: None,
parent_id: None,
creator_id: 2671355,
created_at: '2019-12-11T22:36:50.000000Z',
assignee_id: None,
assigner_id: None,
url: 'https://todoist.com/showTask?id=2995104339'
)
{
id: 2995104339,
content: 'Buy Milk',
description: '',
commentCount: 0,
completed: false,
order: 1,
priority: 1,
projectId: 2203306141,
labelIds: [],
sectionId: null,
parentId: null,
creator: 2671355,
created: '2019-12-11T22:36:50.000000Z',
assigner: null,
url: 'https://todoist.com/showTask?id=2995104339'
}
Next, let's add a new task to our project.
Again, we are sending a POST
request, this time to the tasks
endpoint at https://api.todoist.com/rest/v1/tasks
.
As with all requests we provide the Authorization
header. We also provide the Content-Type: application/json
header
and optional X-Request-Id
as we are making a POST
request.
We send JSON again in the post body. In this case we set the content
of the task to Buy Milk
.
We set the optional project_id
to the id
value from the previous response to add the task to our Shopping List project.
For more information on the other optional values you can pass when adding a task, see the Tasks section.
The API responds with 200
status, and a JSON object containing the data for the task.
We'll keep a note of the task id
for use later.
This time, we make a call to the add_task
method on the API client, and we pass a value for the content
of the task.
We set the optional project_id
to the id
value from the previous response to add the task to our Shopping List project.
The API client responds with a Task
object containing the data for the task we created.
We'll keep a note of the task id
for use in the next request.
To add a new task, we make a call to the addTask
method on the API client, and we pass an object containing a content
value.
We also include an optional value for projectId
, with the id
value from the previous response to add the task to our Shopping List project.
The API client responds with an object containing the data for the task we created.
We'll keep a note of the task id
for use in the next request.
Updating a task
Sending the request:
$ curl "https://api.todoist.com/rest/v1/tasks/2995104339" \
-X POST \
--data '{"due_string": "tomorrow"}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer 0123456789abcdef0123456789"
try:
is_success = api.update_task(task_id=2995104339, due_string='tomorrow')
print(is_success)
except Exception as error:
print(error)
api.updateTask(2995104339, { dueString: 'tomorrow' })
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Sometimes we can't get everything done! We'll need to update the task to remember to get that milk tomorrow.
We'll be sending another POST
request to update the task. This time we add the id
of the task to the url of the
tasks
endpoint: https://api.todoist.com/rest/v1/tasks/2995104339
.
We use the same headers for authorization and content-type. We also provide the optional request ID as we have in the previous steps.
This time we'll set the due_string
property of the task to tomorrow
in the JSON post body. The task will be automatically scheduled for tomorrow's date.
You can find more information on due dates in our Help Center.
The API will respond with status 204
to indicate that the request was successful.
We make a call to the update_task
method on the API client, and we pass a task_id
value with the id
for the task we
received in the previous request. We set the due_string
property of the task to tomorrow
, and the task will be automatically
scheduled for tomorrow's date.
The API client responds with a boolean True
value to confirm that the task has been updated.
We make a call to the updateTask
method on the API client, and we pass the id
for the task we received in the previous request.
We also pass an object containing the values we want to update. In this case we set the dueString
property of the task to tomorrow
.
This will cause the task to be automatically scheduled for tomorrow's date.
The API client responds with a boolean true
value to confirm that the task has been updated.
Completing a task
Sending the request:
$ curl "https://api.todoist.com/rest/v1/tasks/2995104339/close" \
-X POST \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer 0123456789abcdef0123456789"
try:
is_success = api.close_task(task_id=2995104339)
print(is_success)
except Exception as error:
print(error)
api.closeTask(2995104339)
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
We finally finished our task! It's time to mark it complete.
We send another POST
request to the API. This time we add the id
of the task to the url of the tasks endpoint,
followed by the /close
path: https://api.todoist.com/rest/v1/tasks/2995104339/close
.
We'll pass the authorization header but no need to specify the content-type as there is no content to send in the body of this request. We'll provide the optional request ID as we have in the previous examples.
The API will respond with status 204
to indicate that the task has been marked as complete.
We make a call to the close_task
method on the API client, again we pass the task_id
value with the id
for the task.
The API client responds with a boolean True
value to confirm that the task has been marked as complete.
We make a call to the closeTask
method on the API client, and we pass the id
for the task.
The API client responds with a boolean true
value to confirm that the task has been marked as complete.
Deleting a project
Sending the request:
$ curl -X DELETE "https://api.todoist.com/rest/v1/projects/2203306141" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer 0123456789abcdef0123456789"
try:
is_success = api.delete_project(project_id=2203306141)
print(is_success)
except Exception as error:
print(error)
api.deleteProject(2203306141)
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
We finished all the tasks in our Shopping List project, so we can now delete it.
We'll send a DELETE
request this time by adding the id
for the project to the projects
endpoint: https://api.todoist.com/rest/v1/projects/2203306141
.
As before, we set the authorization header with our token and provide a value for the optional request ID header.
The API responds with status 204
to indicate that the project has been successfully deleted.
We make a call to the delete_project
method on the API client, and we pass the project_id
value with the id
for the Shopping List project.
The API client responds with a boolean True
value to confirm that the project has been deleted.
We make a call to the deleteProject
method on the API client, and we pass the id
for the Shopping List project.
The API client responds with a boolean true
value to confirm that the project has been deleted.
Next Steps
That's all there is to it! We've covered the basic concepts of interacting with the Todoist REST API and SDK clients.
You can find details of all the available endpoints and parameters for the various Todoist entity types in the reference documentation below.
In order to make requests for other users you'll need to obtain an auth token from them. You can find details on how to implement this in the Authorization guide.
Authorization
An authenticated request with authorization header:
$ curl -X GET \
https://api.todoist.com/rest/v1/projects \
-H "Authorization: Bearer $token"
In order to make authorized calls to the REST API, your application must provide
an authorization header
with the appropriate Bearer $token
. For working through the examples, you can obtain your personal API token
from the integrations settings for your account.
To authenticate other users your application will need to obtain a token from them using the OAuth protocol. For information on how to obtain a token from our service using OAuth, please see the authorization guide.
Note that we're using $token
on all of our curl
examples, so you can define a temporary environment variable
containing your token and easily copy & paste curl
commands into your terminal.
Projects
An example Project object:
{
"id": 2203306141,
"name": "Shopping List",
"comment_count": 10,
"order": 1,
"color": 47,
"shared": false,
"favorite": false,
"parent_id": 220325187,
"team_inbox": false,
"inbox_project": false,
"url": "https://todoist.com/showProject?id=2203306141"
}
Project(
id: 2203306141,
name: 'Shopping List',
comment_count: 10,
order: 1,
color: 47,
shared: False,
favorite: False,
team_inbox: False,
inbox_project: False,
url: 'https://todoist.com/showProject?id=2203306141'
parent_id: None
)
{
id: 2203306141,
order: 1,
color: 47,
name: 'Shopping List',
commentCount: 10,
shared: false,
favorite: false,
url: 'https://todoist.com/showProject?id=2203306141',
}
Properties
Property | Description |
---|---|
id Integer | Project ID. |
name String | Project name. |
color Integer | A numeric ID representing the color of the project icon. Refer to the id column in the Colors guide for more info. |
parent_id Integer | ID of parent project (read-only, absent for top-level projects). |
parent Deprecated Integer | Will be removed in the next API version. Use parent_id . |
order Integer | Project position under the same parent (read-only). |
comment_count Integer | Number of project comments. |
shared Boolean | Whether the project is shared (read-only, a true or false value). |
favorite Boolean | Whether the project is a favorite (a true or false value). |
inbox_project Boolean | Whether the project is Inbox (read-only, true or otherwise this property is not sent). |
team_inbox Boolean | Whether the project is TeamInbox (read-only, true or otherwise this property is not sent). |
sync_id integer | Identifier to find the match between different copies of shared projects. When you share a project, its copy has a different ID for your collaborators. To find a project in a different account that matches yours, you can use the "sync_id" attribute. For non-shared projects the attribute is set to 0 . |
url String | URL to access this project in the Todoist web or mobile applications. |
Get all projects
Get all projects:
$ curl -X GET \
https://api.todoist.com/rest/v1/projects \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
projects = api.get_projects()
print(projects)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getProjects()
.then((projects) => console.log(projects))
.catch((error) => console.log(error))
Example response:
[
{
"id": 220474322,
"name": "Inbox",
"comment_count": 10,
"order": 1,
"color": 47,
"shared": false,
"favorite": false,
"inbox_project": true,
"team_inbox": false,
"url": "https://todoist.com/showProject?id=220474322"
"parent_id": null,
}
]
[
Project(
id: 220474322,
name: 'Inbox',
comment_count: 10,
order: 1,
color: 47,
shared: False,
favorite: False,
inbox_project: True,
team_inbox: False,
url: 'https://todoist.com/showProject?id=220474322'
parent_id: None,
)
]
[
{
id: 220474322,
order: 0,
color: 47,
name: 'Inbox',
commentCount: 10,
shared: false,
favorite: false,
inboxProject: true,
url: 'https://todoist.com/showProject?id=220474322',
}
]
Returns JSON-encoded array containing all user projects.
A successful response has 200 OK
status and application/json
Content-Type.
Create a new project
Create a new project:
$ curl "https://api.todoist.com/rest/v1/projects" \
-X POST \
--data '{"name": "Shopping List"}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
project = api.add_project(name='Shopping List')
print(project)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.addProject({ name: 'Shopping List' })
.then((project) => console.log(project))
.catch((error) => console.log(error))
Example response:
{
"id": 2203306141,
"name": "Shopping List",
"comment_count": 0,
"color": 47,
"shared": false,
"sync_id": 0,
"order": 1,
"favorite": true,
"url": "https://todoist.com/showProject?id=2203306141"
}
Project(
id: 2203306141,
name: "Shopping List",
comment_count: 0,
order: 1,
color: 47,
shared: False,
favorite: True,
is_inbox_project: False,
is_team_inbox: False,
url: "https://todoist.com/showProject?id=2203306141"
parent_id: None,
)
{
id: 2203306141,
order: 0,
color: 47,
name: 'Shopping List',
commentCount: 0,
shared: false,
favorite: false,
url: 'https://todoist.com/showProject?id=2203306141',
}
Creates a new project and returns it as a JSON object.
A successful response has 200 OK
status and application/json
Content-Type.
Parameters
Parameter | Required | Description |
---|---|---|
name String | Yes | Name of the project. |
parent_id Integer | No | Parent project ID. |
parent Deprecated Integer | No | Will be removed in the next API version. Use parent_id . |
color Integer | No | A numeric ID representing the color of the project icon. Refer to the id column in the Colors guide for more info. |
favorite Boolean | No | Whether the project is a favorite (a true or false value). |
Get a project
Get a project:
$ curl "https://api.todoist.com/rest/v1/projects/2203306141" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
project = api.get_project(project_id=2203306141)
print(project)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getProject(2203306141)
.then((project) => console.log(project))
.catch((error) => console.log(error))
Example response:
{
"id": 2203306141,
"name": "Shopping List",
"comment_count": 0,
"color": 47,
"shared": false,
"order": 1,
"favorite": false,
"url": "https://todoist.com/showProject?id=2203306141"
}
Project(
id: 2203306141,
name: "Shopping List",
comment_count: 0,
order: 1,
color: 47,
shared: False,
favorite: False,
inbox_project: False,
team_inbox: False,
sync_id: 0,
url: "https://todoist.com/showProject?id=2203306141"
parent_id: None,
)
{
id: 2203306141,
parentId: null,
order: 0,
color: 47,
name: 'Shopping List',
commentCount: 0,
shared: false,
favorite: false,
url: 'https://todoist.com/showProject?id=2203306141',
}
Returns a JSON object containing a project object related to the given ID.
A successful response has 200 OK
status and application/json
Content-Type.
Update a project
Update a project:
$ curl "https://api.todoist.com/rest/v1/projects/2203306141" \
-X POST \
--data '{"name": "Things To Buy"}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.update_project(project_id=2203306141, name='Things To Buy')
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.updateProject(2203306141, { name: 'Things To Buy' })
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Updates the project for the given ID.
A successful response has 204 No Content
status and an empty body.
Parameters
Parameter | Required | Description |
---|---|---|
name String | No | Name of the project. |
color Integer | No | A numeric ID representing the color of the project icon. Refer to the id column in the Colors guide for more info. |
favorite Boolean | No | Whether the project is a favorite (a true or false value). |
Delete a project
Delete a project:
$ curl -X DELETE "https://api.todoist.com/rest/v1/projects/2203306141" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.delete_project(project_id=2203306141)
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.deleteProject(2203306141)
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Deletes a project.
A successful response has 204 No Content
status and an empty body.
Get all collaborators
Get all collaborators of a shared project:
$ curl -X GET \
"https://api.todoist.com/rest/v1/projects/2203306141/collaborators" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
collaborators = api.get_collaborators(project_id=2203306141)
print(collaborators)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getProjectCollaborators(2203306141)
.then((collaborators) => console.log(collaborators))
.catch((error) => console.log(error))
Example response:
[
{
"id": 2671362,
"name": "Alice",
"email": "alice@example.com"
},
{
"id": 2671366,
"name": "Bob",
"email": "bob@example.com"
}
]
[
Collaborator(
id: 2671362,
name: 'Alice',
email: 'alice@example.com'
),
Collaborator(
id: 2671366,
name: 'Bob',
email: 'bob@example.com'
)
]
[
{
id: 2671362,
name: 'Alice',
email: 'alice@example.com'
},
{
id: 2671366,
name: 'Bob',
email: 'bob@example.com'
}
]
Returns JSON-encoded array containing all collaborators of a shared project.
A successful response has 200 OK
status and application/json
Content-Type.
Sections
An example Section object:
{
"id": 7025,
"project_id": 2203306141,
"order": 1,
"name": "Groceries"
}
Section(
id: 7025,
project_id: 2203306141,
order: 1,
name: 'Groceries'
)
{
id: 7025,
projectId: 2203306141,
order: 1,
name: 'Groceries'
}
Properties
Property | Description |
---|---|
id Integer | Section id |
project_id Integer | ID of the project section belongs to |
order Integer | Section position among other sections from the same project |
name String | Section name |
Get all sections
Get all sections:
$ curl -s -H "Authorization: Bearer $token" \
https://api.todoist.com/rest/v1/sections?project_id=2203306141
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
sections = api.get_sections(project_id=2203306141)
print(sections)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getSections(2203306141)
.then((sections) => console.log(sections))
.catch((error) => console.log(error))
Example response:
[
{
"id": 7025,
"project_id": 2203306141,
"order": 1,
"name": "Groceries"
}
]
[
Section(
id: 7025,
project_id: 2203306141,
order: 1,
name: 'Groceries'
)
]
[
{
id: 7025,
projectId: 2203306141,
order: 1,
name: 'Groceries'
}
]
Returns a JSON array of all sections.
A successful response has 200 OK
status and application/json
Content-Type.
Parameters
Parameter | Required | Description |
---|---|---|
project_id Integer | No | Filter sections by project ID. |
Create a new section
Create a new section:
$ curl -s -X POST --data '{"project_id":2203306141, "name":"Groceries"}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $token" \
https://api.todoist.com/rest/v1/sections
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
section = api.add_section(name='Groceries', project_id=2203306141)
print(section)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.addSection({ name: 'Groceries', projectId: 2203306141 })
.then((section) => console.log(section))
.catch((error) => console.log(error))
Example response:
{
"id": 7025,
"project_id": 2203306141,
"order": 1,
"name": "Groceries"
}
Section(
id: 7025,
project_id: 2203306141,
order: 1,
name: 'Groceries'
)
{
id: 7025,
projectId: 2203306141,
order: 1,
name: 'Groceries'
}
Creates a new section and returns it as a JSON object.
A successful response has 200 OK
status and application/json
Content-Type.
Parameters
Parameter | Required | Description |
---|---|---|
name String | Yes | Section name |
project_id Integer | Yes | Project ID this section should belong to |
order Integer | No | Order among other sections in a project |
Get a single section
Get a single section:
$ curl -s -H "Authorization: Bearer $token" \
https://api.todoist.com/rest/v1/sections/7025
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
section = api.get_section(section_id=7025)
print(section)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getSection(7025)
.then((section) => console.log(section))
.catch((error) => console.log(error))
Example response:
{
"id": 7025,
"project_id": 2203306141,
"order": 1,
"name": "Groceries"
}
Section(
id: 7025,
project_id: 2203306141,
order: 1,
name: 'Groceries'
)
{
id: 7025,
projectId: 2203306141,
order: 1,
name: 'Groceries'
}
Returns a single section as a JSON object.
A successful response has 200 OK
status and application/json
Content-Type.
Update a section
Update a section:
$ curl -s -X POST --data '{"name":"Supermarket"}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $token" \
https://api.todoist.com/rest/v1/sections/7025
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.update_section(section_id=7025, name='Supermarket')
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.updateSection(7025, { name: 'Supermarket' })
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Updates the section for the given ID.
A successful response has 204 No Content
status and an empty body.
Parameters
Parameter | Required | Description |
---|---|---|
name String | Yes | Section name |
Delete a section
Delete a section:
$ curl -X DELETE -H "Authorization: Bearer $token" \
https://api.todoist.com/rest/v1/sections/7025
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.delete_section(section_id=7025)
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.deleteSection(7025)
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Deletes a section.
A successful response has 204 No Content
status and an empty body.
Tasks
An example Task object:
{
"assignee": 2671142,
"assigner": 2671362,
"comment_count": 10,
"completed": true,
"content": "Buy Milk",
"description": "",
"due": {
"date": "2016-09-01",
"datetime": "2016-09-01T09:00:00Z",
"recurring": false,
"string": "tomorrow at 12",
"timezone": "Europe/Moscow"
},
"id": 2995104339,
"label_ids": [
2156154810,
2156154820,
2156154826
],
"order": 1,
"priority": 1,
"project_id": 2203306141,
"section_id": 7025,
"parent_id": 2995104589,
"url": "https://todoist.com/showTask?id=2995104339"
}
Task(
assignee: 2671142,
assigner: 2671362,
comment_count: 10,
completed: True,
content: 'Buy Milk',
description: '',
due: {
date: '2016-09-01',
datetime: '2016-09-01T09:00:00Z',
recurring: False,
string: 'tomorrow at 12',
timezone: 'Europe/Moscow'
},
id: 2995104339,
label_ids: [
2156154810,
2156154820,
2156154826
],
order: 1,
priority: 1,
project_id: 2203306141,
section_id: 7025,
parent_id: 2995104589,
url: 'https://todoist.com/showTask?id=2995104339'
)
{
assignee: 2671362,
assigner: 2671355,
commentCount: 10,
completed: false,
content: 'Buy Milk',
description: '',
due: {
date: '2016-09-01',
recurring: false,
datetime: '2016-09-01T09:00:00Z',
string: 'tomorrow at 12',
timezone: 'Europe/Moscow'
},
id: 2995104339,
labelsId: [ 2156154810, 2156154820, 2156154826 ],
order: 1,
priority: 1,
projectId: 2203306141,
sectionId: 7025,
parentId: 2995104589,
url: 'https://todoist.com/showTask?id=2995104339'
}
Properties
Property | Description |
---|---|
id Integer | Task ID. |
project_id Integer | Task's project ID (read-only). |
section_id Integer | ID of section task belongs to. |
content String | Task content. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. |
description String | A description for the task. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. |
completed Boolean | Flag to mark completed tasks. |
label_ids Array of Integers | Array of label IDs, associated with a task. |
parent_id Integer | ID of parent task (read-only, absent for top-level tasks). |
parent Deprecated Integer | Will be removed in the next API version. Use parent_id . |
order Integer | Position under the same parent or project for top-level tasks (read-only). |
priority Integer | Task priority from 1 (normal, default value) to 4 (urgent). |
due Object | object representing task due date/time (described below). |
url String | URL to access this task in the Todoist web or mobile applications. |
comment_count Integer | Number of task comments. |
assignee Integer | The responsible user ID (if set, and only for shared tasks). |
assigner Integer | The ID of the user who assigned the task. 0 if the task is unassigned. |
Due object
Parameter | Required | Description |
---|---|---|
string String | Yes | Human defined date in arbitrary format. |
date String | Yes | Date in format YYYY-MM-DD corrected to user's timezone. |
recurring Boolean | Yes | Whether the task has a recurring due date. |
datetime String | No | Only returned if exact due time set (i.e. it's not a whole-day task), date and time in RFC3339 format in UTC. |
timezone String | No | Only returned if exact due time set, user's timezone definition either in tzdata-compatible format ("Europe/Berlin") or as a string specifying east of UTC offset as "UTC±HH:MM" (i.e. "UTC-01:00"). |
Get active tasks
Get active tasks:
$ curl -X GET \
https://api.todoist.com/rest/v1/tasks \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
tasks = api.get_tasks()
print(tasks)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getTasks()
.then((tasks) => console.log(tasks))
.catch((error) => console.log(error))
Example response:
[
{
"id": 2995104339,
"project_id": 2203306141,
"section_id": 7025,
"parent_id": 2995104589,
"content": "Buy Milk",
"description": "",
"comment_count": 10,
"assignee": 2671142,
"assigner": 2671362,
"order": 1,
"priority": 1,
"url": "https://todoist.com/showTask?id=2995104339"
},
...
]
[
Task(
id: 2995104339,
project_id: 2203306141,
section_id: 7025,
parent_id: 2995104589,
content: 'Buy Milk',
description: '',
comment_count: 10,
assignee: 2671142,
assigner: 2671362,
order: 1,
priority: 1,
url: 'https://todoist.com/showTask?id=2995104339'
...
)
[
{
id: 2995104339,
projectId: 2203306141,
sectionId: 7025,
parentId: 2995104589,
content: 'Buy Milk',
description: '',
commentCount: 10,
assignee: 2671362,
assigner: 2671355,
order: 1,
priority: 1,
url: 'https://todoist.com/showTask?id=2995104339'
]
Returns a JSON-encoded array containing all active tasks.
A successful response has 200 OK
status and application/json
Content-Type.
Parameters
Parameter | Required | Description |
---|---|---|
project_id Integer | No | Filter tasks by project ID. |
section_id Integer | No | Filter tasks by section ID. |
label_id Integer | No | Filter tasks by label. |
filter String | No | Filter by any supported filter. |
lang String | No | IETF language tag defining what language filter is written in, if differs from default English. |
ids Array of integers | No | A list of the task IDs to retrieve, this should be a comma separated list. |
Precedence of parameters
When fetching a list of tasks, the API will do so in the following order:
- filter
(with or without lang
)
- ids
- label_id
/project_id
/section_id
If you include a filter and IDs, only the filter will be used. If you include IDs and project_id, only IDs is used, and so on.
Create a new task
Create a new task:
$ curl "https://api.todoist.com/rest/v1/tasks" \
-X POST \
--data '{"content": "Buy Milk", "due_string": "tomorrow at 12:00", "due_lang": "en", "priority": 4}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
task = api.add_task(
content='Buy Milk',
due_string='tomorrow at 12:00',
due_lang='en',
priority=4,
)
print(task)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.addTask({
content: 'Buy Milk',
dueString: 'tomorrow at 12:00',
dueLang: 'en',
priority: 4
})
.then((task) => console.log(task))
.catch((error) => console.log(error))
Example response:
{
"comment_count": 0,
"completed": false,
"content": "Buy Milk",
"description": "",
"due": {
"date": "2016-09-01",
"datetime": "2016-09-01T11:00:00Z",
"recurring": false,
"string": "2017-07-01 12:00",
"timezone": "Europe/Lisbon"
},
"id": 2995104339,
"order": 1,
"priority": 4,
"project_id": 2203306141,
"section_id": 7025,
"parent_id": 2995104589,
"url": "https://todoist.com/showTask?id=2995104339"
}
Task(
comment_count: 0,
completed: False,
content: "Buy Milk",
description: "",
due: {
date: "2016-09-01",
datetime: "2016-09-01T11:00:00Z",
recurring: False,
string: "2017-07-01 12:00",
timezone: "Europe/Lisbon"
},
id: 2995104339,
order: 1,
priority: 4,
project_id: 2203306141,
section_id: 7025,
parent_id: 2995104589,
url: "https://todoist.com/showTask?id=2995104339"
)
{
commentCount: 0,
completed: False,
content: "Buy Milk",
description: "",
due: {
date: "2016-09-01",
datetime: "2016-09-01T11:00:00Z",
recurring: False,
string: "2017-07-01 12:00",
timezone: "Europe/Lisbon"
},
id: 2995104339,
order: 1,
priority: 4,
projectId: 2203306141,
sectionId: 7025,
parentId: 2995104589,
url: "https://todoist.com/showTask?id=2995104339"
}
Creates a new task and returns it as a JSON object.
A successful response has 200 OK
status and application/json
Content-Type.
JSON body parameters
Parameter | Required | Description |
---|---|---|
content String | Yes | Task content. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. |
description String | No | A description for the task. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. |
project_id Integer | No | Task project ID. If not set, task is put to user's Inbox. |
section_id Integer | No | ID of section to put task into. |
parent_id Integer | No | Parent task ID. |
parent Deprecated Integer | No | Will be removed in the next API version. Use parent_id . |
order Integer | No | Non-zero integer value used by clients to sort tasks under the same parent. |
label_ids Array of Integers | No | IDs of labels associated with the task. |
priority Integer | No | Task priority from 1 (normal) to 4 (urgent). |
due_string String | No | Human defined task due date (ex.: "next Monday", "Tomorrow"). Value is set using local (not UTC) time. |
due_date String | No | Specific date in YYYY-MM-DD format relative to user’s timezone. |
due_datetime String | No | Specific date and time in RFC3339 format in UTC. |
due_lang String | No | 2-letter code specifying language in case due_string is not written in English. |
assignee Integer | No | The responsible user ID (if set, and only for shared tasks). |
Please note that only one of the due_*
fields can be used at
the same time (due_lang
is a special case).
Get an active task
Get an active task:
$ curl "https://api.todoist.com/rest/v1/tasks/2995104339" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
task = api.get_task(task_id=2995104339)
print(task)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getTask(2995104339)
.then((task) => console.log(task))
.catch((error) => console.log(error))
Example response:
{
"assignee": 2671142,
"assigner": 2671362,
"comment_count": 0,
"completed": false,
"content": "Buy Milk",
"description": "",
"due": {
"date": "2016-09-01",
"datetime": "2016-09-01T11:00:00Z",
"recurring": false,
"string": "2017-07-01 12:00",
"timezone": "Europe/Lisbon"
},
"id": 2995104339,
"order": 1,
"priority": 1,
"project_id": 2203306141,
"section_id": 7025,
"parent_id": 2995104589,
"url": "https://todoist.com/showTask?id=2995104339"
}
{
"assignee": 2671142,
"assigner": 2671362,
"comment_count": 0,
"completed": False,
"content": "Buy Milk",
"description": "",
"due": {
"date": "2016-09-01",
"datetime": "2016-09-01T11:00:00Z",
"recurring": False,
"string": "2017-07-01 12:00",
"timezone": "Europe/Lisbon"
},
"id": 2995104339,
"order": 1,
"priority": 1,
"project_id": 2203306141,
"section_id": 7025,
"parent_id": 2995104589,
"url": "https://todoist.com/showTask?id=2995104339"
}
Returns a single active (non-completed) task by ID as a JSON object.
A successful response has 200 OK
status and application/json
Content-Type.
Update a task
Update a task:
$ curl "https://api.todoist.com/rest/v1/tasks/2995104339" \
-X POST \
--data '{"content": "Buy Coffee"}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.update_task(task_id=2995104339, content='Buy Coffee')
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.updateTask(2995104339, { content: 'Buy Coffee' })
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Updates a task.
A successful response has 204 No Content
status and an empty body.
JSON body parameters
Parameter | Required | Description |
---|---|---|
content String | No | Task content. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. |
description String | No | A description for the task. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. |
label_ids Array of Integers | No | IDs of labels associated with the task. |
priority Integer | No | Task priority from 1 (normal) to 4 (urgent). |
due_string String | No | Human defined task due date (ex.: "next Monday", "Tomorrow"). Value is set using local (not UTC) time. |
due_date String | No | Specific date in YYYY-MM-DD format relative to user’s timezone. |
due_datetime String | No | Specific date and time in RFC3339 format in UTC. |
due_lang String | No | 2-letter code specifying language in case due_string is not written in English. |
assignee | No | The responsible user ID or 0 to unset (for shared tasks). |
Please note that only one of the due_*
fields can be used at
the same time (due_lang
is a special case).
Close a task
Close a task:
$ curl -X POST "https://api.todoist.com/rest/v1/tasks/2995104339/close" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.close_task(task_id=2995104339)
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.closeTask(2995104339)
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Closes a task.
A successful response has 204 No Content
status and an empty body.
The command performs in the same way as our official clients:
- Root tasks are marked complete and moved to history, along with their subtasks.
- Subtasks are marked complete but not moved to history until their parent task is completed.
- Tasks with recurring due dates will be scheduled to their next occurrence.
Reopen a task
Reopen a task:
$ curl -X POST "https://api.todoist.com/rest/v1/tasks/2995104339/reopen" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.reopen_task(task_id=2995104339)
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.reopenTask(2995104339)
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Reopens a task.
A successful response has 204 No Content
status and an empty body.
The command performs in the same way as our official clients and can be used on both completed tasks and any task in the user's account history.
The behavior varies depending on the type of task and its current state:
- Regular tasks are reinstated from the history as normal unchecked tasks (their subtasks will not be reinstated).
- Completed subtasks of an active task are marked as uncompleted.
- Subtasks that were moved to history are reinstated as root-level tasks.
- Active tasks with recurring due dates are ignored.
Delete a task
Delete a task:
$ curl -X DELETE "https://api.todoist.com/rest/v1/tasks/2995104339" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.delete_task(task_id=2995104339)
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.deleteTask(2995104339)
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Deletes a task.
A successful response has 204 No Content
status and an empty body.
Comments
An example Comment object:
{
"content": "Need one bottle of milk",
"id": 2992679862,
"posted": "2016-09-22T07:00:00Z",
"project_id": 2203306141,
"task_id": 2995104339,
"attachment": {
"file_name": "File.pdf",
"file_type": "application/pdf",
"file_url": "https://cdn-domain.tld/path/to/file.pdf",
"resource_type": "file"
}
}
Comment(
content: 'Need one bottle of milk',
id: 2992679862,
posted: '2016-09-22T07:00:00Z',
project_id: 2203306141,
task_id: 2995104339,
attachment: {
file_name: 'File.pdf',
file_type: 'application/pdf',
file_url: 'https://cdn-domain.tld/path/to/file.pdf',
resource_type: 'file'
}
)
{
content: 'Need one bottle of milk',
id: 2992679862,
posted: '2016-09-22T07:00:00.000000Z',
projectId: null,
taskId: 2995104339,
attachment: {
fileName: 'File.pdf',
fileType: 'application/pdf',
fileUrl: 'https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf',
resourceType: 'file'
}
}
Properties
Property | Description |
---|---|
id Integer | Comment ID. |
task_id Integer | Comment's task ID (for task comments). |
project_id Integer | Comment's project ID (for project comments). |
posted String | Date and time when comment was added, RFC3339 format in UTC. |
content String | Comment content. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. |
attachment Object | Attachment file (optional). |
The optional attachment attribute describes object with attachment metadata. Format of this object depends on the kind of attachment it describes, see Sync API documentation for format details.
Get all comments
Get all comments:
$ curl "https://api.todoist.com/rest/v1/comments?task_id=2995104339" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
comments = api.get_comments(task_id=2995104339)
print(comments)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getComments({ taskId: 2995104339 })
.then((comments) => console.log(comments))
.catch((error) => console.log(error))
Example response:
[
{
"id": 2992679862,
"task_id": 2995104339,
"content": "Need one bottle of milk",
"posted": "2016-09-22T07:00:00Z",
"attachment": {
"resource_type": "file",
"file_url": "https://cdn-domain.tld/path/to/file.pdf",
"file_type": "application/pdf",
"file_name": "File.pdf"
}
}
...
]
[
Comment(
id: 2992679862,
task_id: 2995104339,
content: 'Need one bottle of milk',
posted: '2016-09-22T07:00:00Z',
attachment: {
resource_type: 'file',
file_url: 'https://cdn-domain.tld/path/to/file.pdf',
file_type: 'application/pdf',
file_name: 'File.pdf'
}
)
...
]
Returns a JSON-encoded array of all comments for a given task_id
or project_id
.
Note that one of task_id
or project_id
arguments is required.
A successful response has 200 OK
status and application/json
Content-Type.
Parameters
Parameter | Required | Description |
---|---|---|
project_id Integer | Yes (or task_id ) |
ID of the project used to filter comments. |
task_id Integer | Yes (or project_id ) |
ID of the task used to filter comments. |
Create a new comment
Create a new comment:
$ cat > /tmp/note.json
{
"task_id": 2995104339,
"content": "Need one bottle of milk",
"attachment": {
"resource_type": "file",
"file_url": "https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf",
"file_type": "application/pdf",
"file_name": "File.pdf"
}
}
^C
$ curl "https://api.todoist.com/rest/v1/comments" \
-X POST \
--data @/tmp/note.json \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
comment = api.add_comment(
content='Need one bottle of milk',
task_id=2995104339,
attachment={
"resource_type": "file",
"file_url": "https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf",
"file_type": "application/pdf",
"file_name": "File.pdf"
}
)
print(comment)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.addComment({
taskId: 2995104339,
content: 'Need one bottle of milk',
attachment: {
resourceType: 'file',
fileUrl: 'https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf',
fileType: 'application/pdf',
fileName: 'File.pdf',
},
})
.then((comment) => console.log(comment))
.catch((error) => console.log(error))
Example response:
{
"id": 2992679862,
"content": "Need one bottle of milk",
"task_id": 2995104339,
"posted": "2016-09-22T07:00:00Z",
"attachment": {
"resource_type": "file",
"file_url": "https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf",
"file_type": "application/pdf",
"file_name": "File.pdf"
}
}
Comment(
id: 2992679862,
content: 'Need one bottle of milk',
task_id: 2995104339,
posted: '2016-09-22T07:00:00Z',
attachment: {
resource_type: 'file',
file_url: 'https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf',
file_type: 'application/pdf',
file_name: 'File.pdf'
}
)
{
content: 'Need one bottle of milk',
id: 2992679862,
posted: '2016-09-22T07:00:00.000000Z',
projectId: null,
taskId: 2995104339,
attachment: {
fileName: 'File.pdf',
fileType: 'application/pdf',
fileUrl: 'https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf',
resourceType: 'file'
}
}
Creates a new comment on a project or task and returns it as a JSON object.
Note that one of task_id
or project_id
arguments is required.
A successful response has 200 OK
status and application/json
Content-Type.
JSON body parameters
Parameter | Required | Description |
---|---|---|
task_id Integer | Yes (or project_id ) |
Comment's task ID (for task comments). |
project_id Integer | Yes (or task_id ) |
Comment's project ID (for project comments). |
content String | Yes | Comment content. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. |
attachment Object | No | Object for attachment object. |
Get a comment
Get a comment:
$ curl "https://api.todoist.com/rest/v1/comments/2992679862" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
comment = api.get_comment(comment_id=2992679862)
print(comment)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getComment(2992679862)
.then((comment) => console.log(comment))
.catch((error) => console.log(error))
Example response:
{
"id": 2992679862,
"content": "Need one bottle of milk",
"task_id": 2995104339,
"posted": "2016-09-22T07:00:00Z",
"attachment": {
"resource_type": "file",
"file_url": "https://cdn-domain.tld/path/to/file.pdf",
"file_type": "application/pdf",
"file_name": "File.pdf"
}
}
Comment(
id: 2992679862,
content: 'Need one bottle of milk',
task_id: 2995104339,
posted: '2016-09-22T07:00:00Z',
attachment: {
resource_type: 'file',
file_url: 'https://cdn-domain.tld/path/to/file.pdf',
file_type: 'application/pdf',
file_name: 'File.pdf'
}
)
{
content: 'Need one bottle of milk',
id: 2992679862,
posted: '2016-09-22T07:00:00.000000Z',
projectId: null,
taskId: 2995104339,
attachment: {
fileName: 'File.pdf',
fileType: 'application/pdf',
fileUrl: 'https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf',
resourceType: 'file'
}
}
Returns a single comment as a JSON object.
A successful response has 200 OK
status and application/json
Content-Type.
Update a comment
Update a comment:
$ curl "https://api.todoist.com/rest/v1/comments/2992679862" \
-X POST \
--data '{"content": "Need two bottles of milk"}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.update_comment(
comment_id=2995104339,
content='Need two bottles of milk'
)
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.updateComment(2995104339, { content: 'Need two bottles of milk' })
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Updates a comment.
A successful response has 204 No Content
status and an empty body.
JSON body parameters
Parameter | Required | Description |
---|---|---|
content String | Yes | New content for the comment. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center. |
Delete a comment
Delete a comment:
$ curl -X DELETE "https://api.todoist.com/rest/v1/comments/2992679862" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.delete_comment(comment_id=2995104339)
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.deleteComment(2995104339)
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Deletes a comment.
A successful response has 204 No Content
status and an empty body.
Labels
An example Label object:
{
"id": 2156154810,
"name": "Food",
"color": 47,
"order": 1,
"favorite": false
}
Label(
id: 2156154810,
name: 'Food',
color: 47,
order: 1,
favorite: False
)
{
id: 2156154810,
name: 'Food',
color: 47,
order: 1,
isFavorite: false
}
Properties
Property | Description |
---|---|
id Integer | Label ID. |
name String | Label name. |
color Integer | A numeric ID representing the color of the label icon. Refer to the id column in the Colors guide for more info. |
order Integer | Number used by clients to sort list of labels. |
favorite Boolean | Whether the label is a favorite (a true or false value). |
Get all labels
Get all labels:
$ curl "https://api.todoist.com/rest/v1/labels" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
labels = api.get_labels()
print(labels)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getLabels()
.then((labels) => console.log(labels))
.catch((error) => console.log(error))
Example response:
[
{
"id": 2156154810,
"name": "Food",
"color": 47,
"order": 1,
"favorite": false
}
...
]
[
Label(
id: 2156154810,
name: 'Food',
color: 47,
order: 1,
favorite: False
)
]
[
{
id: 2156154810,
name: 'Food',
color: 47,
order: 1,
isFavorite: false
}
]
Returns a JSON-encoded array containing all user labels.
A successful response has 200 OK
status and application/json
Content-Type.
Create a new label
Create a new label:
$ curl "https://api.todoist.com/rest/v1/labels" \
-X POST \
--data '{"name": "Food"}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
label = api.add_label(name='Food')
print(label)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.addLabel({ name: 'Food' })
.then((label) => console.log(label))
.catch((error) => console.log(error))
Example response:
{
"id": 2156154810,
"name": "Food",
"color": 47,
"order": 1,
"favorite": false
}
Label(
id: 2156154810,
name: 'Food',
color: 47,
order: 1,
favorite: False
)
{
id: 2156154810,
name: 'Food',
color: 47,
order: 1,
isFavorite: false
}
Creates a new label and returns its object as JSON.
A successful response has 200 OK
status and application/json
Content-Type.
JSON body parameters
Parameter | Required | Description |
---|---|---|
name String | Yes | Name of the label. |
order Integer | No | Label order. |
color Integer | No | A numeric ID representing the color of the label icon. Refer to the id column in the Colors guide for more info. |
favorite Boolean | No | Whether the label is a favorite (a true or false value). |
Get a label
Get a label:
$ curl "https://api.todoist.com/rest/v1/labels/2156154810" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
label = api.get_label(label_id=2156154810)
print(label)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.getLabel(2156154810)
.then((label) => console.log(label))
.catch((error) => console.log(error))
Example response:
{
"id": 2156154810,
"name": "Food",
"color": 47,
"order": 1,
"favorite": false
}
Label(
id: 2156154810,
name: 'Food',
color: 47,
order: 1,
favorite: False
)
{
id: 2156154810,
name: 'Food',
color: 47,
order: 1,
isFavorite: false
}
Returns a label by ID.
A successful response has 200 OK
status and application/json
Content-Type.
Update a label
Update a label:
$ curl "https://api.todoist.com/rest/v1/labels/2156154810" \
-X POST \
--data '{"name": "Drinks"}' \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.update_label(label_id=2156154810, name='Drinks')
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.updateLabel(2156154810, { name: 'Drinks' })
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Updates a label.
A successful response has 204 No Content
status and an empty body.
JSON body parameters
Parameter | Required | Description |
---|---|---|
name String | No | New name of the label. |
order Integer | No | Number that is used by clients to sort list of labels. |
color Integer | No | A numeric ID representing the color of the label icon. Refer to the id column in the Colors guide for more info. |
favorite Boolean | No | Whether the label is a favorite (a true or false value). |
Delete a label
Delete a label:
$ curl -X DELETE "https://api.todoist.com/rest/v1/labels/2156154810" \
-H "Authorization: Bearer $token"
from todoist_api_python.api import TodoistAPI
api = TodoistAPI('0123456789abcdef0123456789')
try:
is_success = api.delete_label(label_id=2156154810)
print(is_success)
except Exception as error:
print(error)
import { TodoistApi } from '@doist/todoist-api-typescript'
const api = new TodoistApi('0123456789abcdef0123456789')
api.deleteLabel(2156154810)
.then((isSuccess) => console.log(isSuccess))
.catch((error) => console.log(error))
The API returns an empty response with status 204. SDK clients will respond with
true
to indicate success.
Deletes a label.
A successful response has 204 No Content
status and an empty body.
Request Limits
Payload Size
There is currently a 1 MiB HTTP request body limit on POST requests.
Header Size
Total size of HTTP headers cannot exceed 65 KiB.
Processing Timeouts
There is a processing timeout of 15 seconds on each request.
Rate Limiting
For each user, you can make a maximum of 450 requests within a 15 minute period.