TodoistApi
A client for interacting with the Todoist Sync API. This class provides methods to manage tasks, projects, sections, labels, and comments in Todoist.
Example
const api = new TodoistApi('your-api-token');
// Get all tasks
const tasks = await api.getTasks();
// Create a new task
const newTask = await api.addTask({
content: 'My new task',
projectId: '12345'
});
Constructors
new TodoistApi()
new TodoistApi(authToken: string, baseUrl?: string): TodoistApi
Parameters
| Parameter | Type | Description |
|---|---|---|
authToken | string | Your Todoist API token. |
baseUrl? | string | Optional custom API base URL. If not provided, defaults to Todoist's standard API endpoint |
Returns
Methods
addComment()
addComment(args: AddCommentArgs, requestId?: string): Promise<Comment>
Adds a comment to a task or project.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | AddCommentArgs | Parameters for creating the comment, such as content and the target task or project ID. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Comment>
A promise that resolves to the created comment.
addLabel()
addLabel(args: AddLabelArgs, requestId?: string): Promise<Label>
Adds a new label.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | AddLabelArgs | Label creation parameters such as name. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Label>
A promise that resolves to the created label.
addProject()
addProject(args: AddProjectArgs, requestId?: string): Promise<Project>
Creates a new project with the provided parameters.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | AddProjectArgs | Project creation parameters such as name or color. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Project>
A promise that resolves to the created project.
addSection()
addSection(args: AddSectionArgs, requestId?: string): Promise<Section>
Creates a new section within a project.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | AddSectionArgs | Section creation parameters such as name or project ID. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Section>
A promise that resolves to the created section.
addTask()
addTask(args: AddTaskArgs, requestId?: string): Promise<Task>
Creates a new task with the provided parameters.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | AddTaskArgs | Task creation parameters such as content, due date, or priority. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Task>
A promise that resolves to the created task.
closeTask()
closeTask(id: string, requestId?: string): Promise<boolean>
Closes (completes) a task by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the task to close. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<boolean>
A promise that resolves to true if successful.
deleteComment()
deleteComment(id: string, requestId?: string): Promise<boolean>
Deletes a comment by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the comment to delete. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<boolean>
A promise that resolves to true if successful.
deleteLabel()
deleteLabel(id: string, requestId?: string): Promise<boolean>
Deletes a label by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the label to delete. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<boolean>
A promise that resolves to true if successful.
deleteProject()
deleteProject(id: string, requestId?: string): Promise<boolean>
Deletes a project by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the project to delete. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<boolean>
A promise that resolves to true if successful.
deleteSection()
deleteSection(id: string, requestId?: string): Promise<boolean>
Deletes a section by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the section to delete. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<boolean>
A promise that resolves to true if successful.
deleteTask()
deleteTask(id: string, requestId?: string): Promise<boolean>
Deletes a task by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the task to delete. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<boolean>
A promise that resolves to true if successful.
getComment()
getComment(id: string): Promise<Comment>
Retrieves a specific comment by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the comment to retrieve. |
Returns
Promise<Comment>
A promise that resolves to the requested comment.
getComments()
getComments(args:
| GetTaskCommentsArgs
| GetProjectCommentsArgs): Promise<GetCommentsResponse>
Retrieves all comments associated with a task or project.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | | GetTaskCommentsArgs | GetProjectCommentsArgs | Parameters for retrieving comments, such as task ID or project ID. |
Returns
Promise<GetCommentsResponse>
A promise that resolves to an array of comments.
getLabel()
getLabel(id: string): Promise<Label>
Retrieves a label by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the label. |
Returns
Promise<Label>
A promise that resolves to the requested label.
getLabels()
getLabels(args: GetLabelsArgs): Promise<GetLabelsResponse>
Retrieves all labels.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | GetLabelsArgs | Optional filter parameters. |
Returns
Promise<GetLabelsResponse>
A promise that resolves to an array of labels.
getProject()
getProject(id: string): Promise<Project>
Retrieves a project by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the project. |
Returns
Promise<Project>
A promise that resolves to the requested project.
getProjectCollaborators()
getProjectCollaborators(projectId: string, args: GetProjectCollaboratorsArgs): Promise<GetProjectCollaboratorsResponse>
Retrieves a list of collaborators for a specific project.
Parameters
| Parameter | Type | Description |
|---|---|---|
projectId | string | The unique identifier of the project. |
args | GetProjectCollaboratorsArgs | Optional parameters to filter collaborators. |
Returns
Promise<GetProjectCollaboratorsResponse>
A promise that resolves to an array of collaborators for the project.
getProjects()
getProjects(args: GetProjectsArgs): Promise<GetProjectsResponse>
Retrieves all projects with optional filters.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | GetProjectsArgs | Optional filters for retrieving projects. |
Returns
Promise<GetProjectsResponse>
A promise that resolves to an array of projects.
getSection()
getSection(id: string): Promise<Section>
Retrieves a single section by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the section. |
Returns
Promise<Section>
A promise that resolves to the requested section.
getSections()
getSections(args: GetSectionsArgs): Promise<GetSectionsResponse>
Retrieves all sections within a specific project or matching criteria.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | GetSectionsArgs | Filter parameters such as project ID. |
Returns
Promise<GetSectionsResponse>
A promise that resolves to an array of sections.
getSharedLabels()
getSharedLabels(args?: GetSharedLabelsArgs): Promise<GetSharedLabelsResponse>
Retrieves a list of shared labels.
Parameters
| Parameter | Type | Description |
|---|---|---|
args? | GetSharedLabelsArgs | Optional parameters to filter shared labels. |
Returns
Promise<GetSharedLabelsResponse>
A promise that resolves to an array of shared labels.
getTask()
getTask(id: string): Promise<Task>
Retrieves a single active (non-completed) task by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the task. |
Returns
Promise<Task>
A promise that resolves to the requested task.
getTasks()
getTasks(args: GetTasksArgs): Promise<GetTasksResponse>
Retrieves a list of active tasks filtered by specific parameters.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | GetTasksArgs | Filter parameters such as project ID, label ID, or due date. |
Returns
Promise<GetTasksResponse>
A promise that resolves to an array of tasks.
moveTasks()
moveTasks(
ids: string[],
args: MoveTaskArgs,
requestId?: string): Promise<Task[]>
Moves existing tasks by their ID to either a different parent/section/project.
Parameters
| Parameter | Type | Description |
|---|---|---|
ids | string[] | The unique identifier of the tasks to be moved. |
args | MoveTaskArgs | The paramets that should contain only one of projectId, sectionId, or parentId |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Task[]>
- A promise that resolves to an array of the updated tasks.
quickAddTask()
quickAddTask(args: QuickAddTaskArgs): Promise<Task>
Quickly adds a task using natural language processing for due dates.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | QuickAddTaskArgs | Quick add task parameters, including content and due date. |
Returns
Promise<Task>
A promise that resolves to the created task.
removeSharedLabel()
removeSharedLabel(args: RemoveSharedLabelArgs): Promise<boolean>
Removes a shared label.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | RemoveSharedLabelArgs | Parameters for removing the shared label. |
Returns
Promise<boolean>
A promise that resolves to true if successful.
renameSharedLabel()
renameSharedLabel(args: RenameSharedLabelArgs): Promise<boolean>
Renames an existing shared label.
Parameters
| Parameter | Type | Description |
|---|---|---|
args | RenameSharedLabelArgs | Parameters for renaming the shared label, including the current and new name. |
Returns
Promise<boolean>
A promise that resolves to true if successful.
reopenTask()
reopenTask(id: string, requestId?: string): Promise<boolean>
Reopens a previously closed (completed) task by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the task to reopen. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<boolean>
A promise that resolves to true if successful.
updateComment()
updateComment(
id: string,
args: UpdateCommentArgs,
requestId?: string): Promise<Comment>
Updates an existing comment by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the comment to update. |
args | UpdateCommentArgs | Update parameters such as new content. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Comment>
A promise that resolves to the updated comment.
updateLabel()
updateLabel(
id: string,
args: UpdateLabelArgs,
requestId?: string): Promise<Label>
Updates an existing label by its ID.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the label to update. |
args | UpdateLabelArgs | Update parameters such as name or color. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Label>
A promise that resolves to the updated label.
updateProject()
updateProject(
id: string,
args: UpdateProjectArgs,
requestId?: string): Promise<Project>
Updates an existing project by its ID with the provided parameters.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the project to update. |
args | UpdateProjectArgs | Update parameters such as name or color. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Project>
A promise that resolves to the updated project.
updateSection()
updateSection(
id: string,
args: UpdateSectionArgs,
requestId?: string): Promise<Section>
Updates a section by its ID with the provided parameters.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the section to update. |
args | UpdateSectionArgs | Update parameters such as name or project ID. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Section>
A promise that resolves to the updated section.
updateTask()
updateTask(
id: string,
args: UpdateTaskArgs,
requestId?: string): Promise<Task>
Updates an existing task by its ID with the provided parameters.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | The unique identifier of the task to update. |
args | UpdateTaskArgs | Update parameters such as content, priority, or due date. |
requestId? | string | Optional unique identifier for idempotency. |
Returns
Promise<Task>
A promise that resolves to the updated task.