TodoistApi

Constructors

Constructor

new TodoistApi(authToken: string, options?: TodoistApiOptions): TodoistApi;

Parameters

Parameter	Type	Description
`authToken`	`string`	Your Todoist API token.
`options?`	`TodoistApiOptions`	Optional configuration options

Returns

TodoistApi

Methods

acceptWorkspaceInvitation()

acceptWorkspaceInvitation(args: WorkspaceInvitationActionArgs, requestId?: string): Promise<{
  id: string;
  inviterId: string;
  isExistingUser: boolean;
  role: "ADMIN" | "MEMBER" | "GUEST";
  userEmail: string;
  workspaceId: string;
}>;

Accepts a workspace invitation.

Parameters

Parameter	Type	Description
`args`	`WorkspaceInvitationActionArgs`	Arguments including invite code.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<{ id: string; inviterId: string; isExistingUser: boolean; role: "ADMIN" | "MEMBER" | "GUEST"; userEmail: string; workspaceId: string; }>

The accepted invitation.

addComment()

addComment(args: AddCommentArgs, requestId?: string): Promise<{
  content: string;
  fileAttachment:   | {
     fileDuration?: number | null;
     fileName?: string | null;
     fileSize?: number | null;
     fileType?: string | null;
     fileUrl?: string | null;
     image?: string | null;
     imageHeight?: number | null;
     imageWidth?: number | null;
     resourceType: string;
     title?: string | null;
     uploadState?: "completed" | "pending" | null;
     url?: string | null;
   }
     | null;
  id: string;
  isDeleted: boolean;
  postedAt: string;
  postedUid: string;
  projectId?: string;
  reactions: Record<string, string[]> | null;
  taskId: string | undefined;
  uidsToNotify: string[] | null;
}>;

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 custom identifier for the request.

Returns

Promise<{ content: string; fileAttachment: | { fileDuration?: number | null; fileName?: string | null; fileSize?: number | null; fileType?: string | null; fileUrl?: string | null; image?: string | null; imageHeight?: number | null; imageWidth?: number | null; resourceType: string; title?: string | null; uploadState?: "completed" | "pending" | null; url?: string | null; } | null; id: string; isDeleted: boolean; postedAt: string; postedUid: string; projectId?: string; reactions: Record<string, string[]> | null; taskId: string | undefined; uidsToNotify: string[] | null; }>

A promise that resolves to the created comment.

addFolder()

addFolder(args: AddFolderArgs, requestId?: string): Promise<{
[key: string]: unknown;
  childOrder: number;
  defaultOrder: number;
  id: string;
  isDeleted: boolean;
  name: string;
  workspaceId: string;
}>;

Creates a new folder.

Parameters

Parameter	Type	Description
`args`	`AddFolderArgs`	Folder creation parameters including name and workspace ID.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<{ [key: string]: unknown; childOrder: number; defaultOrder: number; id: string; isDeleted: boolean; name: string; workspaceId: string; }>

A promise that resolves to the created folder.

addLabel()

addLabel(args: AddLabelArgs, requestId?: string): Promise<{
  color: string;
  id: string;
  isFavorite: boolean;
  name: string;
  order: number | null;
}>;

Adds a new label.

Parameters

Parameter	Type	Description
`args`	`AddLabelArgs`	Label creation parameters such as name.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<{ color: string; id: string; isFavorite: boolean; name: string; order: number | null; }>

A promise that resolves to the created label.

addLocationReminder()

addLocationReminder(args: {
  locLat: string;
  locLong: string;
  locTrigger: "on_enter" | "on_leave";
  name: string;
  notifyUid?: string;
  radius?: number;
  taskId: string;
}, requestId?: string): Promise<
  | {
[key: string]: unknown;
  id: string;
  isDeleted: boolean;
  itemId: string;
  locLat: string;
  locLong: string;
  locTrigger: "on_enter" | "on_leave";
  name: string;
  notifyUid: string;
  projectId?: string;
  radius: number;
  type: "location";
}
  | {
[key: string]: unknown;
  due: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  notifyUid: string;
  projectId?: string;
  type: "absolute";
}
  | {
[key: string]: unknown;
  due?: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  minuteOffset: number;
  notifyUid: string;
  projectId?: string;
  type: "relative";
}>;

Creates a location reminder for a task.

Parameters

Parameter	Type	Description
`args`	{ `locLat`: `string`; `locLong`: `string`; `locTrigger`: `"on_enter"` \| `"on_leave"`; `name`: `string`; `notifyUid?`: `string`; `radius?`: `number`; `taskId`: `string`; }	Location reminder creation parameters.
`args.locLat`	`string`	-
`args.locLong?`	`string`	-
`args.locTrigger?`	`"on_enter"` \| `"on_leave"`	-
`args.name?`	`string`	-
`args.notifyUid?`	`string`	-
`args.radius?`	`number`	-
`args.taskId?`	`string`	-
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise< | { [key: string]: unknown; id: string; isDeleted: boolean; itemId: string; locLat: string; locLong: string; locTrigger: "on_enter" | "on_leave"; name: string; notifyUid: string; projectId?: string; radius: number; type: "location"; } | { [key: string]: unknown; due: { date: string; datetime?: string | null; isRecurring: boolean; lang?: string | null; string: string; timezone?: string | null; }; id: string; isDeleted: boolean; isUrgent?: boolean; itemId: string; notifyUid: string; projectId?: string; type: "absolute"; } | { [key: string]: unknown; due?: { date: string; datetime?: string | null; isRecurring: boolean; lang?: string | null; string: string; timezone?: string | null; }; id: string; isDeleted: boolean; isUrgent?: boolean; itemId: string; minuteOffset: number; notifyUid: string; projectId?: string; type: "relative"; }>

A promise that resolves to the created reminder.

addProject()

addProject(args: AddProjectArgs, requestId?: string): Promise<
  | {
  canAssignTasks: boolean;
  childOrder: number;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  id: string;
  inboxProject: boolean;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isShared: boolean;
  name: string;
  parentId: string | null;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  folderId: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isInviteOnly: boolean | null;
  isLinkSharingEnabled: boolean;
  isShared: boolean;
  name: string;
  role: string | null;
  status: string;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
  workspaceId: string;
}>;

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 custom identifier for the request.

Returns

Promise< | { canAssignTasks: boolean; childOrder: number; color: string; createdAt: string | null; defaultOrder: number; description: string; id: string; inboxProject: boolean; isArchived: boolean; isCollapsed: boolean; isDeleted: boolean; isFavorite: boolean; isFrozen: boolean; isShared: boolean; name: string; parentId: string | null; updatedAt: string | null; url: string; viewStyle: string; } | { access?: { visibility: "restricted" | "team" | "public"; }; canAssignTasks: boolean; childOrder: number; collaboratorRoleDefault: string; color: string; createdAt: string | null; defaultOrder: number; description: string; folderId: string | null; id: string; isArchived: boolean; isCollapsed: boolean; isDeleted: boolean; isFavorite: boolean; isFrozen: boolean; isInviteOnly: boolean | null; isLinkSharingEnabled: boolean; isShared: boolean; name: string; role: string | null; status: string; updatedAt: string | null; url: string; viewStyle: string; workspaceId: string; }>

A promise that resolves to the created project.

addReminder()

addReminder(args: AddReminderArgs, requestId?: string): Promise<
  | {
[key: string]: unknown;
  id: string;
  isDeleted: boolean;
  itemId: string;
  locLat: string;
  locLong: string;
  locTrigger: "on_enter" | "on_leave";
  name: string;
  notifyUid: string;
  projectId?: string;
  radius: number;
  type: "location";
}
  | {
[key: string]: unknown;
  due: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  notifyUid: string;
  projectId?: string;
  type: "absolute";
}
  | {
[key: string]: unknown;
  due?: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  minuteOffset: number;
  notifyUid: string;
  projectId?: string;
  type: "relative";
}>;

Creates a time-based reminder for a task.

Parameters

Parameter	Type	Description
`args`	`AddReminderArgs`	Reminder creation parameters for relative or absolute reminders.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the created reminder.

addSection()

addSection(args: AddSectionArgs, requestId?: string): Promise<{
  addedAt: string;
  archivedAt: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: string;
  url: string;
  userId: string;
}>;

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 custom identifier for the request.

Returns

Promise<{ addedAt: string; archivedAt: string | null; id: string; isArchived: boolean; isCollapsed: boolean; isDeleted: boolean; name: string; projectId: string; sectionOrder: number; updatedAt: string; url: string; userId: string; }>

A promise that resolves to the created section.

addTask()

addTask(args: AddTaskArgs, requestId?: string): Promise<{
  addedAt: string | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: string | null;
  content: string;
  dayOrder: number;
  deadline:   | {
     date: string;
     lang: string;
   }
     | null;
  description: string;
  due:   | {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
   }
     | null;
  duration:   | {
     amount: number;
     unit: "minute" | "day";
   }
     | null;
  id: string;
  isCollapsed: boolean;
  isDeleted: boolean;
  isUncompletable: boolean;
  labels: string[];
  parentId: string | null;
  priority: number;
  projectId: string;
  responsibleUid: string | null;
  sectionId: string | null;
  updatedAt: string | null;
  url: string;
  userId: string;
}>;

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 custom identifier for the request.

Returns

Promise<{ addedAt: string | null; addedByUid: string | null; assignedByUid: string | null; checked: boolean; childOrder: number; completedAt: string | null; content: string; dayOrder: number; deadline: | { date: string; lang: string; } | null; description: string; due: | { date: string; datetime?: string | null; isRecurring: boolean; lang?: string | null; string: string; timezone?: string | null; } | null; duration: | { amount: number; unit: "minute" | "day"; } | null; id: string; isCollapsed: boolean; isDeleted: boolean; isUncompletable: boolean; labels: string[]; parentId: string | null; priority: number; projectId: string; responsibleUid: string | null; sectionId: string | null; updatedAt: string | null; url: string; userId: string; }>

A promise that resolves to the created task.

addWorkspace()

addWorkspace(args: AddWorkspaceArgs, requestId?: string): Promise<{
  createdAt: string | undefined;
  creatorId: string;
  id: string;
  inviteCode: string;
  isGuestAllowed: boolean;
  isLinkSharingEnabled: boolean;
  limits?: {
   [key: string]: any;
     current: Record<string, any> | null;
     next: Record<string, any> | null;
  };
  logoBig?: string | null;
  logoMedium?: string | null;
  logoS640?: string | null;
  logoSmall?: string | null;
  name: string;
  plan: "STARTER" | "BUSINESS";
  properties: Record<string, unknown>;
  role?: "ADMIN" | "MEMBER" | "GUEST";
}>;

Creates a new workspace.

Parameters

Parameter	Type	Description
`args`	`AddWorkspaceArgs`	The arguments for creating the workspace.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<{ createdAt: string | undefined; creatorId: string; id: string; inviteCode: string; isGuestAllowed: boolean; isLinkSharingEnabled: boolean; limits?: { [key: string]: any; current: Record<string, any> | null; next: Record<string, any> | null; }; logoBig?: string | null; logoMedium?: string | null; logoS640?: string | null; logoSmall?: string | null; name: string; plan: "STARTER" | "BUSINESS"; properties: Record<string, unknown>; role?: "ADMIN" | "MEMBER" | "GUEST"; }>

A promise that resolves to the created workspace.

analyzeProjectHealth()

analyzeProjectHealth(projectId: string, requestId?: string): Promise<{
  description?: string | null;
  descriptionSummary?: string | null;
  isStale: boolean;
  projectId?: string | null;
  status: "UNKNOWN" | "ON_TRACK" | "AT_RISK" | "CRITICAL" | "EXCELLENT" | "ERROR";
  taskRecommendations?:   | {
     recommendation: string;
     taskId: string;
   }[]
     | null;
  updatedAt?: string | null;
  updateInProgress: boolean;
}>;

Triggers a health analysis for a project.

Parameters

Parameter	Type	Description
`projectId`	`string`	The unique identifier of the project.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<{ description?: string | null; descriptionSummary?: string | null; isStale: boolean; projectId?: string | null; status: "UNKNOWN" | "ON_TRACK" | "AT_RISK" | "CRITICAL" | "EXCELLENT" | "ERROR"; taskRecommendations?: | { recommendation: string; taskId: string; }[] | null; updatedAt?: string | null; updateInProgress: boolean; }>

A promise that resolves to the updated project health data.

archiveProject()

archiveProject(id: string, requestId?: string): Promise<
  | {
  canAssignTasks: boolean;
  childOrder: number;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  id: string;
  inboxProject: boolean;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isShared: boolean;
  name: string;
  parentId: string | null;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  folderId: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isInviteOnly: boolean | null;
  isLinkSharingEnabled: boolean;
  isShared: boolean;
  name: string;
  role: string | null;
  status: string;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
  workspaceId: string;
}>;

Archives a project by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the project to archive.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the updated project.

archiveSection()

archiveSection(id: string, requestId?: string): Promise<{
  addedAt: string;
  archivedAt: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: string;
  url: string;
  userId: string;
}>;

Archives a section by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the section to archive.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the updated section.

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 custom identifier for the request.

Returns

Promise<boolean>

A promise that resolves to true if successful.

createProjectFromTemplate()

createProjectFromTemplate(args: CreateProjectFromTemplateArgs, requestId?: string): Promise<CreateProjectFromTemplateResponse>;

Creates a new project from a template file.

Parameters

Parameter	Type	Description
`args`	`CreateProjectFromTemplateArgs`	Arguments including project name, template file, and optional workspace ID.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<CreateProjectFromTemplateResponse>

A promise that resolves to the created project data.

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 custom identifier for the request.

Returns

Promise<boolean>

A promise that resolves to true if successful.

deleteFolder()

deleteFolder(id: string, requestId?: string): Promise<boolean>;

Deletes a folder by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the folder to delete.
`requestId?`	`string`	Optional custom identifier for the request.

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 custom identifier for the request.

Returns

Promise<boolean>

A promise that resolves to true if successful.

deleteLocationReminder()

deleteLocationReminder(id: string, requestId?: string): Promise<boolean>;

Deletes a location reminder by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the location reminder to delete.
`requestId?`	`string`	Optional custom identifier for the request.

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 custom identifier for the request.

Returns

Promise<boolean>

A promise that resolves to true if successful.

deleteReminder()

deleteReminder(id: string, requestId?: string): Promise<boolean>;

Deletes a time-based reminder by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the reminder to delete.
`requestId?`	`string`	Optional custom identifier for the request.

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 custom identifier for the request.

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 custom identifier for the request.

Returns

Promise<boolean>

A promise that resolves to true if successful.

deleteUpload()

deleteUpload(args: DeleteUploadArgs, requestId?: string): Promise<boolean>;

Deletes an uploaded file by its URL.

Parameters

Parameter	Type	Description
`args`	`DeleteUploadArgs`	The file URL to delete.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<boolean>

A promise that resolves to true if deletion was successful.

Example

await api.deleteUpload({
  fileUrl: 'https://cdn.todoist.com/...'
})

deleteWorkspace()

deleteWorkspace(id: string, requestId?: string): Promise<boolean>;

Deletes a workspace by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the workspace to delete.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<boolean>

A promise that resolves to true if successful.

deleteWorkspaceInvitation()

deleteWorkspaceInvitation(args: DeleteWorkspaceInvitationArgs, requestId?: string): Promise<{
  id: string;
  inviterId: string;
  isExistingUser: boolean;
  role: "ADMIN" | "MEMBER" | "GUEST";
  userEmail: string;
  workspaceId: string;
}>;

Deletes a workspace invitation (admin only).

Parameters

Parameter	Type	Description
`args`	`DeleteWorkspaceInvitationArgs`	Arguments including workspace ID and user email.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<{ id: string; inviterId: string; isExistingUser: boolean; role: "ADMIN" | "MEMBER" | "GUEST"; userEmail: string; workspaceId: string; }>

The deleted invitation.

disableEmailForwarding()

disableEmailForwarding(args: DisableEmailArgs, requestId?: string): Promise<boolean>;

Disables email forwarding for an object.

Parameters

Parameter	Type	Description
`args`	`DisableEmailArgs`	Arguments including object type and ID.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<boolean>

A promise that resolves to true if successful.

downloadBackup()

downloadBackup(args: DownloadBackupArgs): Promise<FileResponse>;

Downloads a backup file as binary data.

Parameters

Parameter	Type	Description
`args`	`DownloadBackupArgs`	Arguments including the backup file URL (from getBackups).

Returns

Promise<FileResponse>

A promise that resolves to a response with binary data accessible via arrayBuffer().

exportTemplateAsFile()

exportTemplateAsFile(args: ExportTemplateFileArgs): Promise<string>;

Exports a project as a template file (CSV format).

Parameters

Parameter	Type	Description
`args`	`ExportTemplateFileArgs`	Arguments including project ID and optional date format preference.

Returns

Promise<string>

A promise that resolves to the template file content as a string.

exportTemplateAsUrl()

exportTemplateAsUrl(args: ExportTemplateUrlArgs): Promise<ExportTemplateUrlResponse>;

Exports a project as a template URL.

Parameters

Parameter	Type	Description
`args`	`ExportTemplateUrlArgs`	Arguments including project ID and optional date format preference.

Returns

Promise<ExportTemplateUrlResponse>

A promise that resolves to the file name and URL.

getActivityLogs()

getActivityLogs(args?: GetActivityLogsArgs): Promise<GetActivityLogsResponse>;

Retrieves activity logs with optional filters.

Parameters

Parameter	Type	Description
`args`	`GetActivityLogsArgs`	Optional filter parameters for activity logs.

Returns

Promise<GetActivityLogsResponse>

A promise that resolves to a paginated response of activity events.

getAllCompletedTasks()

getAllCompletedTasks(args?: GetAllCompletedTasksArgs): Promise<GetAllCompletedTasksResponse>;

Retrieves all completed tasks with optional filters.

Uses offset-based pagination rather than cursor-based.

Parameters

Parameter	Type	Description
`args`	`GetAllCompletedTasksArgs`	Optional parameters including project ID, label, date range, and pagination.

Returns

Promise<GetAllCompletedTasksResponse>

A promise that resolves to completed tasks with associated project and section data.

getAllWorkspaceInvitations()

getAllWorkspaceInvitations(args?: {
  workspaceId?: number;
}, requestId?: string): Promise<AllWorkspaceInvitationsResponse>;

Gets all workspace invitations (admin only).

Parameters

Parameter	Type	Description
`args`	{ `workspaceId?`: `number`; }	-
`args.workspaceId?`	`number`	-
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<AllWorkspaceInvitationsResponse>

Array of email addresses with pending invitations.

getArchivedProjects()

getArchivedProjects(args?: GetArchivedProjectsArgs): Promise<GetArchivedProjectsResponse>;

Retrieves all archived projects with optional filters.

Parameters

Parameter	Type	Description
`args`	`GetArchivedProjectsArgs`	Optional filters for retrieving archived projects.

Returns

Promise<GetArchivedProjectsResponse>

A promise that resolves to an array of archived projects.

getArchivedProjectsCount()

getArchivedProjectsCount(args?: GetArchivedProjectsCountArgs): Promise<GetArchivedProjectsCountResponse>;

Counts the number of archived projects.

Parameters

Parameter	Type	Description
`args`	`GetArchivedProjectsCountArgs`	Optional parameters to filter the count.

Returns

Promise<GetArchivedProjectsCountResponse>

A promise that resolves to the count of archived projects.

getBackups()

getBackups(args?: GetBackupsArgs): Promise<{
  url: string;
  version: string;
}[]>;

Retrieves a list of available backups.

Parameters

Parameter	Type	Description
`args`	`GetBackupsArgs`	Optional parameters including MFA token.

Returns

Promise<{ url: string; version: string; }[]>

A promise that resolves to an array of backups.

getComment()

getComment(id: string): Promise<{
  content: string;
  fileAttachment:   | {
     fileDuration?: number | null;
     fileName?: string | null;
     fileSize?: number | null;
     fileType?: string | null;
     fileUrl?: string | null;
     image?: string | null;
     imageHeight?: number | null;
     imageWidth?: number | null;
     resourceType: string;
     title?: string | null;
     uploadState?: "completed" | "pending" | null;
     url?: string | null;
   }
     | null;
  id: string;
  isDeleted: boolean;
  postedAt: string;
  postedUid: string;
  projectId?: string;
  reactions: Record<string, string[]> | null;
  taskId: string | undefined;
  uidsToNotify: string[] | null;
}>;

Retrieves a specific comment by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the comment to retrieve.

Returns

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.

getCompletedTasksByCompletionDate()

getCompletedTasksByCompletionDate(args: GetCompletedTasksByCompletionDateArgs): Promise<GetCompletedTasksResponse>;

Retrieves completed tasks by completion date.

Parameters

Parameter	Type	Description
`args`	`GetCompletedTasksByCompletionDateArgs`	Parameters for filtering, including required since, until.

Returns

Promise<GetCompletedTasksResponse>

A promise that resolves to a paginated response of completed tasks.

getCompletedTasksByDueDate()

getCompletedTasksByDueDate(args: GetCompletedTasksByDueDateArgs): Promise<GetCompletedTasksResponse>;

Retrieves completed tasks by due date.

Parameters

Parameter	Type	Description
`args`	`GetCompletedTasksByDueDateArgs`	Parameters for filtering, including required since, until.

Returns

Promise<GetCompletedTasksResponse>

A promise that resolves to a paginated response of completed tasks.

getFolder()

getFolder(id: string): Promise<{
[key: string]: unknown;
  childOrder: number;
  defaultOrder: number;
  id: string;
  isDeleted: boolean;
  name: string;
  workspaceId: string;
}>;

Retrieves a single folder by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the folder.

Returns

Promise<{ [key: string]: unknown; childOrder: number; defaultOrder: number; id: string; isDeleted: boolean; name: string; workspaceId: string; }>

A promise that resolves to the requested folder.

getFolders()

getFolders(args: GetFoldersArgs): Promise<GetFoldersResponse>;

Retrieves a paginated list of folders.

Parameters

Parameter	Type	Description
`args`	`GetFoldersArgs`	Filter parameters such as workspace ID.

Returns

Promise<GetFoldersResponse>

A promise that resolves to a paginated response of folders.

getFullProject()

getFullProject(id: string, args?: GetFullProjectArgs): Promise<GetFullProjectResponse>;

Retrieves full project data including tasks, sections, collaborators, and notes.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the project.
`args`	`GetFullProjectArgs`	Optional parameters.

Returns

Promise<GetFullProjectResponse>

A promise that resolves to the full project data.

getIdMappings()

getIdMappings(args: GetIdMappingsArgs): Promise<{
  newId: string | null;
  oldId: string | null;
}[]>;

Retrieves ID mappings between old and new IDs.

Parameters

Parameter	Type	Description
`args`	`GetIdMappingsArgs`	Arguments including object type and IDs to look up.

Returns

Promise<{ newId: string | null; oldId: string | null; }[]>

A promise that resolves to an array of ID mappings.

getLabel()

getLabel(id: string): Promise<{
  color: string;
  id: string;
  isFavorite: boolean;
  name: string;
  order: number | null;
}>;

Retrieves a label by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the label.

Returns

Promise<{ color: string; id: string; isFavorite: boolean; name: string; order: number | null; }>

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.

getLocationReminder()

getLocationReminder(id: string): Promise<
  | {
[key: string]: unknown;
  id: string;
  isDeleted: boolean;
  itemId: string;
  locLat: string;
  locLong: string;
  locTrigger: "on_enter" | "on_leave";
  name: string;
  notifyUid: string;
  projectId?: string;
  radius: number;
  type: "location";
}
  | {
[key: string]: unknown;
  due: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  notifyUid: string;
  projectId?: string;
  type: "absolute";
}
  | {
[key: string]: unknown;
  due?: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  minuteOffset: number;
  notifyUid: string;
  projectId?: string;
  type: "relative";
}>;

Retrieves a location reminder by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the location reminder to retrieve.

Returns

A promise that resolves to the requested reminder.

getLocationReminders()

getLocationReminders(args?: GetLocationRemindersArgs): Promise<GetLocationRemindersResponse>;

Retrieves a paginated list of location-based reminders.

Parameters

Parameter	Type	Description
`args`	`GetLocationRemindersArgs`	Optional parameters including task ID filter and pagination.

Returns

Promise<GetLocationRemindersResponse>

A promise that resolves to a paginated list of location reminders.

getMovedIds()

getMovedIds(args: GetMovedIdsArgs): Promise<{
  newId: string;
  oldId: string;
}[]>;

Retrieves moved IDs for objects that have been migrated.

Parameters

Parameter	Type	Description
`args`	`GetMovedIdsArgs`	Arguments including object type and optional old IDs to look up.

Returns

Promise<{ newId: string; oldId: string; }[]>

A promise that resolves to an array of moved ID pairs.

getOrCreateEmailForwarding()

getOrCreateEmailForwarding(args: GetOrCreateEmailArgs, requestId?: string): Promise<GetOrCreateEmailResponse>;

Gets or creates an email forwarding address for an object.

Parameters

Parameter	Type	Description
`args`	`GetOrCreateEmailArgs`	Arguments including object type and ID.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<GetOrCreateEmailResponse>

A promise that resolves to the email address.

getProductivityStats()

getProductivityStats(): Promise<{
  completedCount: number;
  daysItems: {
     date: string;
     items: {
        completed: number;
        id: string;
     }[];
     totalCompleted: number;
  }[];
  goals: {
     currentDailyStreak: {
        count: number;
        end: string;
        start: string;
     };
     currentWeeklyStreak: {
        count: number;
        end: string;
        start: string;
     };
     dailyGoal: number;
     ignoreDays: number[];
     karmaDisabled: number;
     lastDailyStreak: {
        count: number;
        end: string;
        start: string;
     };
     lastWeeklyStreak: {
        count: number;
        end: string;
        start: string;
     };
     maxDailyStreak: {
        count: number;
        end: string;
        start: string;
     };
     maxWeeklyStreak: {
        count: number;
        end: string;
        start: string;
     };
     user: string;
     userId: string;
     vacationMode: number;
     weeklyGoal: number;
  };
  karma: number;
  karmaGraphData: {
     date: string;
     karmaAvg: number;
  }[];
  karmaLastUpdate: number;
  karmaTrend: string;
  karmaUpdateReasons: {
     negativeKarma: number;
     negativeKarmaReasons: any[];
     newKarma: number;
     positiveKarma: number;
     positiveKarmaReasons: any[];
     time: string;
  }[];
  projectColors: Record<string, string>;
  weekItems: {
     from: string;
     items: {
        completed: number;
        id: string;
     }[];
     to: string;
     totalCompleted: number;
  }[];
}>;

Retrieves productivity stats for the authenticated user.

Returns

Promise<{ completedCount: number; daysItems: { date: string; items: { completed: number; id: string; }[]; totalCompleted: number; }[]; goals: { currentDailyStreak: { count: number; end: string; start: string; }; currentWeeklyStreak: { count: number; end: string; start: string; }; dailyGoal: number; ignoreDays: number[]; karmaDisabled: number; lastDailyStreak: { count: number; end: string; start: string; }; lastWeeklyStreak: { count: number; end: string; start: string; }; maxDailyStreak: { count: number; end: string; start: string; }; maxWeeklyStreak: { count: number; end: string; start: string; }; user: string; userId: string; vacationMode: number; weeklyGoal: number; }; karma: number; karmaGraphData: { date: string; karmaAvg: number; }[]; karmaLastUpdate: number; karmaTrend: string; karmaUpdateReasons: { negativeKarma: number; negativeKarmaReasons: any[]; newKarma: number; positiveKarma: number; positiveKarmaReasons: any[]; time: string; }[]; projectColors: Record<string, string>; weekItems: { from: string; items: { completed: number; id: string; }[]; to: string; totalCompleted: number; }[]; }>

A promise that resolves to the productivity stats.

getProject()

getProject(id: string): Promise<
  | {
  canAssignTasks: boolean;
  childOrder: number;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  id: string;
  inboxProject: boolean;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isShared: boolean;
  name: string;
  parentId: string | null;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  folderId: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isInviteOnly: boolean | null;
  isLinkSharingEnabled: boolean;
  isShared: boolean;
  name: string;
  role: string | null;
  status: string;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
  workspaceId: string;
}>;

Retrieves a project by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the project.

Returns

A promise that resolves to the requested project.

getProjectActivityStats()

getProjectActivityStats(projectId: string, args?: GetProjectActivityStatsArgs): Promise<{
  dayItems: {
     date: string;
     totalCount: number;
  }[];
  weekItems:   | {
     fromDate: string;
     toDate: string;
     totalCount: number;
   }[]
     | null;
}>;

Retrieves activity statistics for a project.

Parameters

Parameter	Type	Description
`projectId`	`string`	The unique identifier of the project.
`args`	`GetProjectActivityStatsArgs`	Optional parameters including weeks and weekly counts flag.

Returns

Promise<{ dayItems: { date: string; totalCount: number; }[]; weekItems: | { fromDate: string; toDate: string; totalCount: number; }[] | null; }>

A promise that resolves to the project activity stats.

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.

getProjectHealth()

getProjectHealth(projectId: string): Promise<{
  description?: string | null;
  descriptionSummary?: string | null;
  isStale: boolean;
  projectId?: string | null;
  status: "UNKNOWN" | "ON_TRACK" | "AT_RISK" | "CRITICAL" | "EXCELLENT" | "ERROR";
  taskRecommendations?:   | {
     recommendation: string;
     taskId: string;
   }[]
     | null;
  updatedAt?: string | null;
  updateInProgress: boolean;
}>;

Retrieves the health status of a project.

Parameters

Parameter	Type	Description
`projectId`	`string`	The unique identifier of the project.

Returns

A promise that resolves to the project health data.

getProjectHealthContext()

getProjectHealthContext(projectId: string): Promise<{
  language?: string | null;
  projectDescription: string | null;
  projectId: string;
  projectMetrics: {
     averageCompletionTime: number | null;
     completedTasks: number;
     overdueTasks: number;
     tasksCompletedThisWeek: number;
     tasksCreatedThisWeek: number;
     totalTasks: number;
  };
  projectName: string;
  tasks: {
     completedAt: string | null;
     completedByUid: string | null;
     content: string;
     createdAt: string;
     deadline?: string | null;
     due?: string | null;
     id: string;
     isCompleted: boolean;
     labels: string[];
     priority: string;
     updatedAt: string;
  }[];
}>;

Retrieves the health context for a project, including metrics and task details.

Parameters

Parameter	Type	Description
`projectId`	`string`	The unique identifier of the project.

Returns

Promise<{ language?: string | null; projectDescription: string | null; projectId: string; projectMetrics: { averageCompletionTime: number | null; completedTasks: number; overdueTasks: number; tasksCompletedThisWeek: number; tasksCreatedThisWeek: number; totalTasks: number; }; projectName: string; tasks: { completedAt: string | null; completedByUid: string | null; content: string; createdAt: string; deadline?: string | null; due?: string | null; id: string; isCompleted: boolean; labels: string[]; priority: string; updatedAt: string; }[]; }>

A promise that resolves to the project health context.

getProjectPermissions()

getProjectPermissions(): Promise<GetProjectPermissionsResponse>;

Retrieves the role-to-action permission mappings for projects.

Returns

Promise<GetProjectPermissionsResponse>

A promise that resolves to the permission mappings.

getProjectProgress()

getProjectProgress(projectId: string): Promise<{
  activeCount: number;
  completedCount: number;
  progressPercent: number;
  projectId: string;
}>;

Retrieves progress information for a project.

Parameters

Parameter	Type	Description
`projectId`	`string`	The unique identifier of the project.

Returns

Promise<{ activeCount: number; completedCount: number; progressPercent: number; projectId: string; }>

A promise that resolves to the project progress data.

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.

getReminder()

getReminder(id: string): Promise<
  | {
[key: string]: unknown;
  id: string;
  isDeleted: boolean;
  itemId: string;
  locLat: string;
  locLong: string;
  locTrigger: "on_enter" | "on_leave";
  name: string;
  notifyUid: string;
  projectId?: string;
  radius: number;
  type: "location";
}
  | {
[key: string]: unknown;
  due: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  notifyUid: string;
  projectId?: string;
  type: "absolute";
}
  | {
[key: string]: unknown;
  due?: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  minuteOffset: number;
  notifyUid: string;
  projectId?: string;
  type: "relative";
}>;

Retrieves a time-based reminder by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the reminder to retrieve.

Returns

A promise that resolves to the requested reminder.

getReminders()

getReminders(args?: GetRemindersArgs): Promise<GetRemindersResponse>;

Retrieves a paginated list of time-based reminders.

Parameters

Parameter	Type	Description
`args`	`GetRemindersArgs`	Optional parameters including task ID filter and pagination.

Returns

Promise<GetRemindersResponse>

A promise that resolves to a paginated list of reminders.

getSection()

getSection(id: string): Promise<{
  addedAt: string;
  archivedAt: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: string;
  url: string;
  userId: string;
}>;

Retrieves a single section by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the section.

Returns

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. If no projectId is provided, all sections are returned.

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<{
  addedAt: string | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: string | null;
  content: string;
  dayOrder: number;
  deadline:   | {
     date: string;
     lang: string;
   }
     | null;
  description: string;
  due:   | {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
   }
     | null;
  duration:   | {
     amount: number;
     unit: "minute" | "day";
   }
     | null;
  id: string;
  isCollapsed: boolean;
  isDeleted: boolean;
  isUncompletable: boolean;
  labels: string[];
  parentId: string | null;
  priority: number;
  projectId: string;
  responsibleUid: string | null;
  sectionId: string | null;
  updatedAt: string | null;
  url: string;
  userId: string;
}>;

Retrieves a single active (non-completed) task by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the task.

Returns

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.

getTasksByFilter()

getTasksByFilter(args: GetTasksByFilterArgs): Promise<GetTasksResponse>;

Retrieves tasks filtered by a filter string.

Parameters

Parameter	Type	Description
`args`	`GetTasksByFilterArgs`	Parameters for filtering tasks, including the query string and optional language.

Returns

Promise<GetTasksResponse>

A promise that resolves to a paginated response of tasks.

getUser()

getUser(): Promise<{
  avatarBig?: string | null;
  avatarMedium?: string | null;
  avatarS640?: string | null;
  avatarSmall?: string | null;
  businessAccountId: string | null;
  completedCount: number;
  completedToday: number;
  dailyGoal: number;
  dateFormat: number;
  daysOff: number[];
  email: string;
  fullName: string;
  id: string;
  inboxProjectId: string;
  isPremium: boolean;
  karma: number;
  karmaTrend: string;
  lang: string;
  nextWeek: number;
  premiumStatus:   | "not_premium"
     | "current_personal_plan"
     | "legacy_personal_plan"
     | "teams_business_member";
  startDay: number;
  startPage: string;
  timeFormat: number;
  tzInfo: {
     gmtString: string;
     hours: number;
     isDst: number;
     minutes: number;
     timezone: string;
  };
  weekendStartDay: number;
  weeklyGoal: number;
}>;

Retrieves information about the authenticated user.

Returns

Promise<{ avatarBig?: string | null; avatarMedium?: string | null; avatarS640?: string | null; avatarSmall?: string | null; businessAccountId: string | null; completedCount: number; completedToday: number; dailyGoal: number; dateFormat: number; daysOff: number[]; email: string; fullName: string; id: string; inboxProjectId: string; isPremium: boolean; karma: number; karmaTrend: string; lang: string; nextWeek: number; premiumStatus: | "not_premium" | "current_personal_plan" | "legacy_personal_plan" | "teams_business_member"; startDay: number; startPage: string; timeFormat: number; tzInfo: { gmtString: string; hours: number; isDst: number; minutes: number; timezone: string; }; weekendStartDay: number; weeklyGoal: number; }>

A promise that resolves to the current user's information.

getWorkspace()

getWorkspace(id: string, requestId?: string): Promise<{
  createdAt: string | undefined;
  creatorId: string;
  id: string;
  inviteCode: string;
  isGuestAllowed: boolean;
  isLinkSharingEnabled: boolean;
  limits?: {
   [key: string]: any;
     current: Record<string, any> | null;
     next: Record<string, any> | null;
  };
  logoBig?: string | null;
  logoMedium?: string | null;
  logoS640?: string | null;
  logoSmall?: string | null;
  name: string;
  plan: "STARTER" | "BUSINESS";
  properties: Record<string, unknown>;
  role?: "ADMIN" | "MEMBER" | "GUEST";
}>;

Retrieves a workspace by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the workspace.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the requested workspace.

getWorkspaceActiveProjects()

getWorkspaceActiveProjects(args: GetWorkspaceProjectsArgs, requestId?: string): Promise<GetProjectsResponse>;

Gets active projects in a workspace with pagination.

Parameters

Parameter	Type	Description
`args`	`GetWorkspaceProjectsArgs`	Arguments including workspace ID, cursor, and limit.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<GetProjectsResponse>

Paginated list of active workspace projects.

getWorkspaceArchivedProjects()

getWorkspaceArchivedProjects(args: GetWorkspaceProjectsArgs, requestId?: string): Promise<GetProjectsResponse>;

Gets archived projects in a workspace with pagination.

Parameters

Parameter	Type	Description
`args`	`GetWorkspaceProjectsArgs`	Arguments including workspace ID, cursor, and limit.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<GetProjectsResponse>

Paginated list of archived workspace projects.

getWorkspaceInsights()

getWorkspaceInsights(workspaceId: string, args?: GetWorkspaceInsightsArgs): Promise<{
  folderId: string | null;
  projectInsights: {
     health:   | {
        description?: string | null;
        descriptionSummary?: string | null;
        isStale: boolean;
        projectId?: string | null;
        status: "UNKNOWN" | "ON_TRACK" | "AT_RISK" | "CRITICAL" | "EXCELLENT" | "ERROR";
        taskRecommendations?:   | {
           recommendation: string;
           taskId: string;
         }[]
           | null;
        updatedAt?: string | null;
        updateInProgress: boolean;
      }
        | null;
     progress:   | {
        activeCount: number;
        completedCount: number;
        progressPercent: number;
        projectId: string;
      }
        | null;
     projectId: string;
  }[];
}>;

Retrieves insights for all projects in a workspace.

Parameters

Parameter	Type	Description
`workspaceId`	`string`	The unique identifier of the workspace.
`args`	`GetWorkspaceInsightsArgs`	Optional parameters including project IDs filter.

Returns

Promise<{ folderId: string | null; projectInsights: { health: | { description?: string | null; descriptionSummary?: string | null; isStale: boolean; projectId?: string | null; status: "UNKNOWN" | "ON_TRACK" | "AT_RISK" | "CRITICAL" | "EXCELLENT" | "ERROR"; taskRecommendations?: | { recommendation: string; taskId: string; }[] | null; updatedAt?: string | null; updateInProgress: boolean; } | null; progress: | { activeCount: number; completedCount: number; progressPercent: number; projectId: string; } | null; projectId: string; }[]; }>

A promise that resolves to workspace insights data.

getWorkspaceInvitations()

getWorkspaceInvitations(args: GetWorkspaceInvitationsArgs, requestId?: string): Promise<WorkspaceInvitationsResponse>;

Gets pending invitations for a workspace.

Parameters

Parameter	Type	Description
`args`	`GetWorkspaceInvitationsArgs`	Arguments including workspace ID.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<WorkspaceInvitationsResponse>

Array of email addresses with pending invitations.

getWorkspaceMembersActivity()

getWorkspaceMembersActivity(args: GetWorkspaceMembersActivityArgs, requestId?: string): Promise<GetWorkspaceMembersActivityResponse>;

Retrieves activity information for workspace members.

Parameters

Parameter	Type	Description
`args`	`GetWorkspaceMembersActivityArgs`	Arguments including workspace ID and optional user/project filters.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<GetWorkspaceMembersActivityResponse>

A promise that resolves to workspace members activity data.

getWorkspacePlanDetails()

getWorkspacePlanDetails(args: GetWorkspacePlanDetailsArgs, requestId?: string): Promise<{
  cancelAtPeriodEnd: boolean;
  currentActiveProjects: number;
  currentMemberCount: number;
  currentPlan: "Business" | "Starter";
  currentPlanStatus: "Active" | "Downgraded" | "Cancelled" | "NeverSubscribed";
  downgradeAt: string | null;
  hasBillingPortal: boolean;
  hasBillingPortalSwitchToAnnual: boolean;
  hasTrialed: boolean;
  isTrialing: boolean;
  maximumActiveProjects: number;
  planPrice:   | {
     amount: string | number;
     currency: string;
     interval?: string;
   }
     | null;
  priceList: {
     amount?: number;
     currency?: string;
     formatted?: string;
     interval?: string;
  }[];
  trialEndsAt: string | null;
  workspaceId: number;
}>;

Gets workspace plan and billing details.

Parameters

Parameter	Type	Description
`args`	`GetWorkspacePlanDetailsArgs`	Arguments including workspace ID.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<{ cancelAtPeriodEnd: boolean; currentActiveProjects: number; currentMemberCount: number; currentPlan: "Business" | "Starter"; currentPlanStatus: "Active" | "Downgraded" | "Cancelled" | "NeverSubscribed"; downgradeAt: string | null; hasBillingPortal: boolean; hasBillingPortalSwitchToAnnual: boolean; hasTrialed: boolean; isTrialing: boolean; maximumActiveProjects: number; planPrice: | { amount: string | number; currency: string; interval?: string; } | null; priceList: { amount?: number; currency?: string; formatted?: string; interval?: string; }[]; trialEndsAt: string | null; workspaceId: number; }>

Workspace plan details.

getWorkspaces()

getWorkspaces(requestId?: string): Promise<{
  createdAt: string | undefined;
  creatorId: string;
  id: string;
  inviteCode: string;
  isGuestAllowed: boolean;
  isLinkSharingEnabled: boolean;
  limits?: {
   [key: string]: any;
     current: Record<string, any> | null;
     next: Record<string, any> | null;
  };
  logoBig?: string | null;
  logoMedium?: string | null;
  logoS640?: string | null;
  logoSmall?: string | null;
  name: string;
  plan: "STARTER" | "BUSINESS";
  properties: Record<string, unknown>;
  role?: "ADMIN" | "MEMBER" | "GUEST";
}[]>;

Retrieves all workspaces for the authenticated user.

Parameters

Parameter	Type	Description
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to an array of workspaces.

Example

const workspaces = await api.getWorkspaces()
workspaces.forEach(workspace => {
  console.log(`${workspace.name} (${workspace.plan}) - Role: ${workspace.role}`)
})

getWorkspaceUsers()

getWorkspaceUsers(args?: GetWorkspaceUsersArgs, requestId?: string): Promise<GetWorkspaceUsersResponse>;

Gets workspace users with pagination.

Parameters

Parameter	Type	Description
`args`	`GetWorkspaceUsersArgs`	Arguments including optional workspace ID, cursor, and limit.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<GetWorkspaceUsersResponse>

Paginated list of workspace users.

getWorkspaceUserTasks()

getWorkspaceUserTasks(args: GetWorkspaceUserTasksArgs, requestId?: string): Promise<GetWorkspaceUserTasksResponse>;

Retrieves tasks assigned to a specific user in a workspace.

Parameters

Parameter	Type	Description
`args`	`GetWorkspaceUserTasksArgs`	Arguments including workspace ID, user ID, and optional project filter.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<GetWorkspaceUserTasksResponse>

A promise that resolves to workspace user tasks.

importTemplateFromId()

importTemplateFromId(args: ImportTemplateFromIdArgs, requestId?: string): Promise<ImportTemplateResponse>;

Imports a template by ID into an existing project.

Parameters

Parameter	Type	Description
`args`	`ImportTemplateFromIdArgs`	Arguments including project ID, template ID, and optional locale.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<ImportTemplateResponse>

A promise that resolves to the import result.

importTemplateIntoProject()

importTemplateIntoProject(args: ImportTemplateIntoProjectArgs, requestId?: string): Promise<ImportTemplateResponse>;

Imports a template file into an existing project.

Parameters

Parameter	Type	Description
`args`	`ImportTemplateIntoProjectArgs`	Arguments including project ID and template file.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<ImportTemplateResponse>

A promise that resolves to the import result.

inviteWorkspaceUsers()

inviteWorkspaceUsers(args: InviteWorkspaceUsersArgs, requestId?: string): Promise<InviteWorkspaceUsersResponse>;

Invites users to a workspace by email.

Parameters

Parameter	Type	Description
`args`	`InviteWorkspaceUsersArgs`	Arguments including workspace ID, email list, and optional role.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<InviteWorkspaceUsersResponse>

A promise that resolves to the list of invited emails.

joinProject()

joinProject(id: string, requestId?: string): Promise<JoinProjectResponse>;

Joins a workspace project.

Only used for workspaces — this endpoint is used to join a workspace project by a workspace user.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the workspace project to join.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<JoinProjectResponse>

A promise that resolves to the full project data after joining.

joinWorkspace()

joinWorkspace(args: JoinWorkspaceArgs, requestId?: string): Promise<{
  customSortingApplied: boolean;
  projectSortPreference: string;
  role: "ADMIN" | "MEMBER" | "GUEST";
  userId: string;
  workspaceId: string;
}>;

Joins a workspace via invitation link or domain auto-join.

Parameters

Parameter	Type	Description
`args`	`JoinWorkspaceArgs`	Arguments including invite code or workspace ID.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<{ customSortingApplied: boolean; projectSortPreference: string; role: "ADMIN" | "MEMBER" | "GUEST"; userId: string; workspaceId: string; }>

Workspace user information.

moveProjectToPersonal()

moveProjectToPersonal(args: MoveProjectToPersonalArgs, requestId?: string): Promise<
  | {
  canAssignTasks: boolean;
  childOrder: number;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  id: string;
  inboxProject: boolean;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isShared: boolean;
  name: string;
  parentId: string | null;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  folderId: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isInviteOnly: boolean | null;
  isLinkSharingEnabled: boolean;
  isShared: boolean;
  name: string;
  role: string | null;
  status: string;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
  workspaceId: string;
}>;

Moves a project to personal.

Parameters

Parameter	Type	Description
`args`	`MoveProjectToPersonalArgs`	The arguments for moving the project.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the moved project.

moveProjectToWorkspace()

moveProjectToWorkspace(args: MoveProjectToWorkspaceArgs, requestId?: string): Promise<
  | {
  canAssignTasks: boolean;
  childOrder: number;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  id: string;
  inboxProject: boolean;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isShared: boolean;
  name: string;
  parentId: string | null;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  folderId: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isInviteOnly: boolean | null;
  isLinkSharingEnabled: boolean;
  isShared: boolean;
  name: string;
  role: string | null;
  status: string;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
  workspaceId: string;
}>;

Moves a project to a workspace.

Parameters

Parameter	Type	Description
`args`	`MoveProjectToWorkspaceArgs`	The arguments for moving the project.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the moved project.

moveTask()

moveTask(
   id: string, 
   args: _RequireExactlyOne, 
   requestId?: string): Promise<{
  addedAt: string | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: string | null;
  content: string;
  dayOrder: number;
  deadline:   | {
     date: string;
     lang: string;
   }
     | null;
  description: string;
  due:   | {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
   }
     | null;
  duration:   | {
     amount: number;
     unit: "minute" | "day";
   }
     | null;
  id: string;
  isCollapsed: boolean;
  isDeleted: boolean;
  isUncompletable: boolean;
  labels: string[];
  parentId: string | null;
  priority: number;
  projectId: string;
  responsibleUid: string | null;
  sectionId: string | null;
  updatedAt: string | null;
  url: string;
  userId: string;
}>;

Moves a task by its ID to either a different parent/section/project.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the task to be moved.
`args`	`_RequireExactlyOne`	The parameters that should contain exactly one of projectId, sectionId, or parentId
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the updated task.

moveTasks()

moveTasks(
   ids: string[], 
   args: _RequireExactlyOne, 
   requestId?: string): Promise<{
  addedAt: string | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: string | null;
  content: string;
  dayOrder: number;
  deadline:   | {
     date: string;
     lang: string;
   }
     | null;
  description: string;
  due:   | {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
   }
     | null;
  duration:   | {
     amount: number;
     unit: "minute" | "day";
   }
     | null;
  id: string;
  isCollapsed: boolean;
  isDeleted: boolean;
  isUncompletable: boolean;
  labels: string[];
  parentId: string | null;
  priority: number;
  projectId: string;
  responsibleUid: string | null;
  sectionId: string | null;
  updatedAt: string | null;
  url: string;
  userId: string;
}[]>;

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`	`_RequireExactlyOne`	The paramets that should contain only one of projectId, sectionId, or parentId
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to an array of the updated tasks.

quickAddTask()

quickAddTask(args: QuickAddTaskArgs): Promise<{
  addedAt: string | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: string | null;
  content: string;
  dayOrder: number;
  deadline:   | {
     date: string;
     lang: string;
   }
     | null;
  description: string;
  due:   | {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
   }
     | null;
  duration:   | {
     amount: number;
     unit: "minute" | "day";
   }
     | null;
  id: string;
  isCollapsed: boolean;
  isDeleted: boolean;
  isUncompletable: boolean;
  labels: string[];
  parentId: string | null;
  priority: number;
  projectId: string;
  responsibleUid: string | null;
  sectionId: string | null;
  updatedAt: string | null;
  url: string;
  userId: string;
}>;

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

A promise that resolves to the created task.

rejectWorkspaceInvitation()

rejectWorkspaceInvitation(args: WorkspaceInvitationActionArgs, requestId?: string): Promise<{
  id: string;
  inviterId: string;
  isExistingUser: boolean;
  role: "ADMIN" | "MEMBER" | "GUEST";
  userEmail: string;
  workspaceId: string;
}>;

Rejects a workspace invitation.

Parameters

Parameter	Type	Description
`args`	`WorkspaceInvitationActionArgs`	Arguments including invite code.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<{ id: string; inviterId: string; isExistingUser: boolean; role: "ADMIN" | "MEMBER" | "GUEST"; userEmail: string; workspaceId: string; }>

The rejected invitation.

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.

removeWorkspaceUser()

removeWorkspaceUser(args: RemoveWorkspaceUserArgs, requestId?: string): Promise<boolean>;

Removes a user from a workspace.

Parameters

Parameter	Type	Description
`args`	`RemoveWorkspaceUserArgs`	Arguments including workspace ID and user ID.
`requestId?`	`string`	Optional custom identifier for the request.

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 custom identifier for the request.

Returns

Promise<boolean>

A promise that resolves to true if successful.

searchCompletedTasks()

searchCompletedTasks(args: SearchCompletedTasksArgs): Promise<GetCompletedTasksResponse>;

Searches completed tasks by query string.

Parameters

Parameter	Type	Description
`args`	`SearchCompletedTasksArgs`	Parameters for searching, including the query string.

Returns

Promise<GetCompletedTasksResponse>

A promise that resolves to a paginated response of completed tasks.

searchLabels()

searchLabels(args: SearchArgs): Promise<GetLabelsResponse>;

Searches labels by name.

Parameters

Parameter	Type	Description
`args`	`SearchArgs`	Search parameters including the query string.

Returns

Promise<GetLabelsResponse>

A promise that resolves to a paginated response of labels.

searchProjects()

searchProjects(args: SearchArgs): Promise<GetProjectsResponse>;

Searches projects by name.

Parameters

Parameter	Type	Description
`args`	`SearchArgs`	Search parameters including the query string.

Returns

Promise<GetProjectsResponse>

A promise that resolves to a paginated response of projects.

searchSections()

searchSections(args: SearchSectionsArgs): Promise<GetSectionsResponse>;

Searches sections by name.

Parameters

Parameter	Type	Description
`args`	`SearchSectionsArgs`	Search parameters including the query string.

Returns

Promise<GetSectionsResponse>

A promise that resolves to a paginated response of sections.

sync()

sync(syncRequest: SyncRequest, requestId?: string): Promise<SyncResponse>;

Executes a raw Sync API request.

This method provides direct access to the Sync API, allowing you to send strongly-typed commands and request specific resource types.

Parameters

Parameter	Type	Description
`syncRequest`	`SyncRequest`	-
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<SyncResponse>

A promise that resolves to the sync response.

Throws

TodoistRequestError if the sync status contains errors.

Example

import { createCommand } from '@doist/todoist-sdk'

const response = await api.sync({
    commands: [
        createCommand('item_add', { content: 'Buy milk' }),
    ],
    resourceTypes: ['items'],
    syncToken: '*',
})

unarchiveProject()

unarchiveProject(id: string, requestId?: string): Promise<
  | {
  canAssignTasks: boolean;
  childOrder: number;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  id: string;
  inboxProject: boolean;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isShared: boolean;
  name: string;
  parentId: string | null;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  folderId: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isInviteOnly: boolean | null;
  isLinkSharingEnabled: boolean;
  isShared: boolean;
  name: string;
  role: string | null;
  status: string;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
  workspaceId: string;
}>;

Unarchives a project by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the project to unarchive.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the updated project.

unarchiveSection()

unarchiveSection(id: string, requestId?: string): Promise<{
  addedAt: string;
  archivedAt: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: string;
  url: string;
  userId: string;
}>;

Unarchives a section by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the section to unarchive.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the updated section.

updateComment()

updateComment(
   id: string, 
   args: UpdateCommentArgs, 
   requestId?: string): Promise<{
  content: string;
  fileAttachment:   | {
     fileDuration?: number | null;
     fileName?: string | null;
     fileSize?: number | null;
     fileType?: string | null;
     fileUrl?: string | null;
     image?: string | null;
     imageHeight?: number | null;
     imageWidth?: number | null;
     resourceType: string;
     title?: string | null;
     uploadState?: "completed" | "pending" | null;
     url?: string | null;
   }
     | null;
  id: string;
  isDeleted: boolean;
  postedAt: string;
  postedUid: string;
  projectId?: string;
  reactions: Record<string, string[]> | null;
  taskId: string | undefined;
  uidsToNotify: string[] | null;
}>;

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 custom identifier for the request.

Returns

A promise that resolves to the updated comment.

updateFolder()

updateFolder(
   id: string, 
   args: UpdateFolderArgs, 
   requestId?: string): Promise<{
[key: string]: unknown;
  childOrder: number;
  defaultOrder: number;
  id: string;
  isDeleted: boolean;
  name: string;
  workspaceId: string;
}>;

Updates an existing folder by its ID.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the folder to update.
`args`	`UpdateFolderArgs`	Update parameters such as name or default order.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<{ [key: string]: unknown; childOrder: number; defaultOrder: number; id: string; isDeleted: boolean; name: string; workspaceId: string; }>

A promise that resolves to the updated folder.

updateLabel()

updateLabel(
   id: string, 
   args: UpdateLabelArgs, 
   requestId?: string): Promise<{
  color: string;
  id: string;
  isFavorite: boolean;
  name: string;
  order: number | null;
}>;

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 custom identifier for the request.

Returns

Promise<{ color: string; id: string; isFavorite: boolean; name: string; order: number | null; }>

A promise that resolves to the updated label.

updateLocationReminder()

updateLocationReminder(
   id: string, 
   args: {
  locLat?: string;
  locLong?: string;
  locTrigger?: "on_enter" | "on_leave";
  name?: string;
  notifyUid?: string;
  radius?: number;
}, 
   requestId?: string): Promise<
  | {
[key: string]: unknown;
  id: string;
  isDeleted: boolean;
  itemId: string;
  locLat: string;
  locLong: string;
  locTrigger: "on_enter" | "on_leave";
  name: string;
  notifyUid: string;
  projectId?: string;
  radius: number;
  type: "location";
}
  | {
[key: string]: unknown;
  due: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  notifyUid: string;
  projectId?: string;
  type: "absolute";
}
  | {
[key: string]: unknown;
  due?: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  minuteOffset: number;
  notifyUid: string;
  projectId?: string;
  type: "relative";
}>;

Updates an existing location reminder.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the location reminder to update.
`args`	{ `locLat?`: `string`; `locLong?`: `string`; `locTrigger?`: `"on_enter"` \| `"on_leave"`; `name?`: `string`; `notifyUid?`: `string`; `radius?`: `number`; }	Location reminder update parameters.
`args.locLat?`	`string`	-
`args.locLong?`	`string`	-
`args.locTrigger?`	`"on_enter"` \| `"on_leave"`	-
`args.name?`	`string`	-
`args.notifyUid?`	`string`	-
`args.radius?`	`number`	-
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the updated reminder.

updateProject()

updateProject(
   id: string, 
   args: UpdateProjectArgs, 
   requestId?: string): Promise<
  | {
  canAssignTasks: boolean;
  childOrder: number;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  id: string;
  inboxProject: boolean;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isShared: boolean;
  name: string;
  parentId: string | null;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: string | null;
  defaultOrder: number;
  description: string;
  folderId: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  isFavorite: boolean;
  isFrozen: boolean;
  isInviteOnly: boolean | null;
  isLinkSharingEnabled: boolean;
  isShared: boolean;
  name: string;
  role: string | null;
  status: string;
  updatedAt: string | null;
  url: string;
  viewStyle: string;
  workspaceId: string;
}>;

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 custom identifier for the request.

Returns

A promise that resolves to the updated project.

updateReminder()

updateReminder(
   id: string, 
   args: UpdateReminderArgs, 
   requestId?: string): Promise<
  | {
[key: string]: unknown;
  id: string;
  isDeleted: boolean;
  itemId: string;
  locLat: string;
  locLong: string;
  locTrigger: "on_enter" | "on_leave";
  name: string;
  notifyUid: string;
  projectId?: string;
  radius: number;
  type: "location";
}
  | {
[key: string]: unknown;
  due: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  notifyUid: string;
  projectId?: string;
  type: "absolute";
}
  | {
[key: string]: unknown;
  due?: {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
  };
  id: string;
  isDeleted: boolean;
  isUrgent?: boolean;
  itemId: string;
  minuteOffset: number;
  notifyUid: string;
  projectId?: string;
  type: "relative";
}>;

Updates an existing time-based reminder.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the reminder to update.
`args`	`UpdateReminderArgs`	Reminder update parameters.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the updated reminder.

updateSection()

updateSection(
   id: string, 
   args: UpdateSectionArgs, 
   requestId?: string): Promise<{
  addedAt: string;
  archivedAt: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: string;
  url: string;
  userId: string;
}>;

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 custom identifier for the request.

Returns

A promise that resolves to the updated section.

updateTask()

updateTask(
   id: string, 
   args: UpdateTaskArgs, 
   requestId?: string): Promise<{
  addedAt: string | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: string | null;
  content: string;
  dayOrder: number;
  deadline:   | {
     date: string;
     lang: string;
   }
     | null;
  description: string;
  due:   | {
     date: string;
     datetime?: string | null;
     isRecurring: boolean;
     lang?: string | null;
     string: string;
     timezone?: string | null;
   }
     | null;
  duration:   | {
     amount: number;
     unit: "minute" | "day";
   }
     | null;
  id: string;
  isCollapsed: boolean;
  isDeleted: boolean;
  isUncompletable: boolean;
  labels: string[];
  parentId: string | null;
  priority: number;
  projectId: string;
  responsibleUid: string | null;
  sectionId: string | null;
  updatedAt: string | null;
  url: string;
  userId: string;
}>;

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. Pass `dueString: null` (or `"no date"`) to clear the due date.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the updated task.

updateWorkspace()

updateWorkspace(
   id: string, 
   args: UpdateWorkspaceArgs, 
   requestId?: string): Promise<{
  createdAt: string | undefined;
  creatorId: string;
  id: string;
  inviteCode: string;
  isGuestAllowed: boolean;
  isLinkSharingEnabled: boolean;
  limits?: {
   [key: string]: any;
     current: Record<string, any> | null;
     next: Record<string, any> | null;
  };
  logoBig?: string | null;
  logoMedium?: string | null;
  logoS640?: string | null;
  logoSmall?: string | null;
  name: string;
  plan: "STARTER" | "BUSINESS";
  properties: Record<string, unknown>;
  role?: "ADMIN" | "MEMBER" | "GUEST";
}>;

Updates an existing workspace.

Parameters

Parameter	Type	Description
`id`	`string`	The unique identifier of the workspace to update.
`args`	`UpdateWorkspaceArgs`	The arguments for updating the workspace.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

A promise that resolves to the updated workspace.

updateWorkspaceUser()

updateWorkspaceUser(args: UpdateWorkspaceUserArgs, requestId?: string): Promise<{
  customSortingApplied: boolean;
  projectSortPreference: string;
  role: "ADMIN" | "MEMBER" | "GUEST";
  userId: string;
  workspaceId: string;
}>;

Updates a workspace user's role.

Parameters

Parameter	Type	Description
`args`	`UpdateWorkspaceUserArgs`	Arguments including workspace ID, user ID, and new role.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<{ customSortingApplied: boolean; projectSortPreference: string; role: "ADMIN" | "MEMBER" | "GUEST"; userId: string; workspaceId: string; }>

A promise that resolves to the updated workspace user view.

uploadFile()

uploadFile(args: UploadFileArgs, requestId?: string): Promise<{
  fileDuration?: number | null;
  fileName?: string | null;
  fileSize?: number | null;
  fileType?: string | null;
  fileUrl?: string | null;
  image?: string | null;
  imageHeight?: number | null;
  imageWidth?: number | null;
  resourceType: string;
  title?: string | null;
  uploadState?: "completed" | "pending" | null;
  url?: string | null;
}>;

Uploads a file and returns attachment metadata. This creates an upload record that can be referenced in tasks or comments.

Parameters

Parameter	Type	Description
`args`	`UploadFileArgs`	Upload parameters including file content, filename, and optional project ID.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<{ fileDuration?: number | null; fileName?: string | null; fileSize?: number | null; fileType?: string | null; fileUrl?: string | null; image?: string | null; imageHeight?: number | null; imageWidth?: number | null; resourceType: string; title?: string | null; uploadState?: "completed" | "pending" | null; url?: string | null; }>

A promise that resolves to the uploaded file's attachment metadata.

Example

// Upload from a file path
const upload = await api.uploadFile({
  file: '/path/to/document.pdf',
  projectId: '12345'
})

// Upload from a Buffer
const buffer = fs.readFileSync('/path/to/document.pdf')
const upload = await api.uploadFile({
  file: buffer,
  fileName: 'document.pdf',  // Required for Buffer/Stream
  projectId: '12345'
})

// Use the returned fileUrl in a comment
await api.addComment({
  content: 'See attached document',
  taskId: '67890',
  attachment: {
    fileUrl: upload.fileUrl,
    fileName: upload.fileName,
    fileType: upload.fileType,
    resourceType: upload.resourceType
  }
})

uploadWorkspaceLogo()

uploadWorkspaceLogo(args: WorkspaceLogoArgs, requestId?: string): Promise<WorkspaceLogoResponse>;

Uploads or updates a workspace logo.

Parameters

Parameter	Type	Description
`args`	`WorkspaceLogoArgs`	Arguments including workspace ID, file, and options.
`requestId?`	`string`	Optional request ID for idempotency.

Returns

Promise<WorkspaceLogoResponse>

Logo information or null if deleted.

viewAttachment()

viewAttachment(commentOrUrl: 
  | string
  | {
  content: string;
  fileAttachment:   | {
     fileDuration?: number | null;
     fileName?: string | null;
     fileSize?: number | null;
     fileType?: string | null;
     fileUrl?: string | null;
     image?: string | null;
     imageHeight?: number | null;
     imageWidth?: number | null;
     resourceType: string;
     title?: string | null;
     uploadState?: "completed" | "pending" | null;
     url?: string | null;
   }
     | null;
  id: string;
  isDeleted: boolean;
  postedAt: string;
  postedUid: string;
  projectId?: string;
  reactions: Record<string, string[]> | null;
  taskId: string | undefined;
  uidsToNotify: string[] | null;
}): Promise<FileResponse>;

Fetches the content of a file attachment from a Todoist comment.

Accepts either a Comment object (extracts the file URL from its attachment) or a direct file URL string. Returns the raw Response object so the caller can read the body in the appropriate format (.arrayBuffer(), .text(), etc.).

Parameters

Parameter	Type	Description
`commentOrUrl`	\| `string` \| { `content`: `string`; `fileAttachment`: \| { `fileDuration?`: `number` \| `null`; `fileName?`: `string` \| `null`; `fileSize?`: `number` \| `null`; `fileType?`: `string` \| `null`; `fileUrl?`: `string` \| `null`; `image?`: `string` \| `null`; `imageHeight?`: `number` \| `null`; `imageWidth?`: `number` \| `null`; `resourceType`: `string`; `title?`: `string` \| `null`; `uploadState?`: `"completed"` \| `"pending"` \| `null`; `url?`: `string` \| `null`; } \| `null`; `id`: `string`; `isDeleted`: `boolean`; `postedAt`: `string`; `postedUid`: `string`; `projectId?`: `string`; `reactions`: `Record`<`string`, `string`[]> \| `null`; `taskId`: `string` \| `undefined`; `uidsToNotify`: `string`[] \| `null`; }	A Comment object with a file attachment, or a file URL string.

Returns

Promise<FileResponse>

The raw fetch Response for the file content.

Throws

Error if a Comment is provided without a file attachment or file URL.

Example

// From a comment object
const comments = await api.getComments({ taskId: '12345' })
const comment = comments.results[0]
const response = await api.viewAttachment(comment)
const imageData = await response.arrayBuffer()

// From a URL string
const response = await api.viewAttachment('https://files.todoist.com/...')
const text = await response.text()

Constructors​

Constructor​

Parameters​

Returns​

Methods​

acceptWorkspaceInvitation()​

Parameters​

Returns​

addComment()​

Parameters​

Returns​

addFolder()​

Parameters​

Returns​

addLabel()​

Parameters​

Returns​

addLocationReminder()​

Parameters​

Returns​

addProject()​

Parameters​

Returns​

addReminder()​

Parameters​

Returns​

addSection()​

Parameters​

Returns​

addTask()​

Parameters​

Returns​

addWorkspace()​

Parameters​

Returns​

analyzeProjectHealth()​

Parameters​

Returns​

archiveProject()​

Parameters​

Returns​

archiveSection()​

Parameters​

Returns​

closeTask()​

Parameters​

Returns​

createProjectFromTemplate()​

Parameters​

Returns​

deleteComment()​

Parameters​

Returns​

deleteFolder()​

Parameters​

Returns​

deleteLabel()​

Parameters​

Returns​

deleteLocationReminder()​

Parameters​

Returns​

deleteProject()​

Parameters​

Returns​

deleteReminder()​

Parameters​

Returns​

deleteSection()​

Parameters​

Returns​

deleteTask()​

Parameters​

Returns​

deleteUpload()​

Parameters​

Returns​

Example​

deleteWorkspace()​

Parameters​

Constructors

Constructor

Parameters

Returns

Methods

acceptWorkspaceInvitation()

Parameters

Returns

addComment()

Parameters

Returns

addFolder()

Parameters

Returns

addLabel()

Parameters

Returns

addLocationReminder()

Parameters

Returns

addProject()

Parameters

Returns

addReminder()

Parameters

Returns

addSection()

Parameters

Returns

addTask()

Parameters

Returns

addWorkspace()

Parameters

Returns

analyzeProjectHealth()

Parameters

Returns

archiveProject()

Parameters

Returns

archiveSection()

Parameters

Returns

closeTask()

Parameters

Returns

createProjectFromTemplate()

Parameters

Returns

deleteComment()

Parameters

Returns

deleteFolder()

Parameters

Returns

deleteLabel()

Parameters

Returns

deleteLocationReminder()

Parameters

Returns

deleteProject()

Parameters

Returns

deleteReminder()

Parameters

Returns

deleteSection()

Parameters

Returns

deleteTask()

Parameters

Returns

deleteUpload()

Parameters

Returns

Example

deleteWorkspace()

Parameters