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;
  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; role: "ADMIN" | "MEMBER" | "GUEST"; userEmail: string; workspaceId: string; }>

The accepted invitation.

addApp()

addApp(args: AddAppArgs, requestId?: string): Promise<{
  appTokenScopes: string[] | null;
  clientId: string;
  createdAt: Date;
  description: string | null;
  displayName: string;
  iconLg: string | null;
  iconMd: string | null;
  iconSm: string | null;
  id: string;
  oauthRedirectUri: string | null;
  serviceUrl: string | null;
  status: "public";
  userId: string;
}>;

Creates a new developer application.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`args`	`AddAppArgs`
`requestId?`	`string`

Returns

Promise<{ appTokenScopes: string[] | null; clientId: string; createdAt: Date; description: string | null; displayName: string; iconLg: string | null; iconMd: string | null; iconSm: string | null; id: string; oauthRedirectUri: string | null; serviceUrl: string | null; status: "public"; userId: string; }>

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: Date;
  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: Date; 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: Date | 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: Date | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: Date | 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: Date | 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: Date | 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: Date | null; url: string; viewStyle: string; } | { access?: { visibility: "restricted" | "team" | "public"; }; canAssignTasks: boolean; childOrder: number; collaboratorRoleDefault: string; color: string; createdAt: Date | 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: Date | 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: Date;
  archivedAt: Date | null;
  description: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: Date;
  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: Date; archivedAt: Date | null; description: string | null; id: string; isArchived: boolean; isCollapsed: boolean; isDeleted: boolean; name: string; projectId: string; sectionOrder: number; updatedAt: Date; url: string; userId: string; }>

A promise that resolves to the created section.

addTask()

addTask(args: AddTaskArgs, requestId?: string): Promise<{
  addedAt: Date | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: Date | 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: Date | 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: Date | null; addedByUid: string | null; assignedByUid: string | null; checked: boolean; childOrder: number; completedAt: Date | 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: Date | null; url: string; userId: string; }>

A promise that resolves to the created task.

addUiExtension()

addUiExtension(args: AddUiExtensionArgs, requestId?: string): Promise<
  | {
  contextType: "task" | "project";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "context-menu";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  composerType: "task" | "comment";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "composer";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "settings";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}>;

Adds a new UI extension to an app.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`args`	`AddUiExtensionArgs`
`requestId?`	`string`

Returns

Promise< | { contextType: "task" | "project"; defVersion: number; description: string; extensionId: string; extensionType: "context-menu"; height: number | null; icon: string | null; id: string; integrationId: string; minimumCardistVersion: string; name: string; url: string; width: number | null; } | { composerType: "task" | "comment"; defVersion: number; description: string; extensionId: string; extensionType: "composer"; height: number | null; icon: string | null; id: string; integrationId: string; minimumCardistVersion: string; name: string; url: string; width: number | null; } | { defVersion: number; description: string; extensionId: string; extensionType: "settings"; height: number | null; icon: string | null; id: string; integrationId: string; minimumCardistVersion: string; name: string; url: string; width: number | null; }>

addWorkspace()

addWorkspace(args: AddWorkspaceArgs, requestId?: string): Promise<{
  createdAt: Date | 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: Date | 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";
  updatedAt?: Date | 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"; updatedAt?: Date | 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: Date | 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: Date | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: Date | 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: Date | 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: Date;
  archivedAt: Date | null;
  description: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: Date;
  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.

cancelPlan()

cancelPlan(args?: CancelPlanArgs, requestId?: string): Promise<BillingPortalUrlResponse>;

Starts a hosted cancellation flow for the current user's plan.

Requires the billing:read_write scope.

Parameters

Parameter	Type	Description
`args?`	`CancelPlanArgs`	Optional cancellation reason details and return URL.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<BillingPortalUrlResponse>

A promise that resolves to the billing portal redirect URL.

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.

createAppTestToken()

createAppTestToken(appId: string, requestId?: string): Promise<{
  accessToken?: string | null;
}>;

Creates (or rotates) a developer test token for an app.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

Promise<{ accessToken?: string | null; }>

createProBillingPortalSession()

createProBillingPortalSession(args: ProBillingPortalArgs, requestId?: string): Promise<BillingPortalUrlResponse>;

Creates a one-time Stripe billing portal session for the current user's Pro plan.

Requires the billing:read_write scope.

Parameters

Parameter	Type	Description
`args`	`ProBillingPortalArgs`	Return URL and optional flow type / promotion code.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<BillingPortalUrlResponse>

A promise that resolves to the billing portal URL.

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.

createWorkspaceBillingPortalSession()

createWorkspaceBillingPortalSession(args: WorkspaceBillingPortalArgs, requestId?: string): Promise<BillingPortalUrlResponse>;

Creates a one-time Stripe billing portal session for a workspace.

Requires the billing:read_write scope.

Parameters

Parameter	Type	Description
`args`	`WorkspaceBillingPortalArgs`	Workspace ID, return URL, and optional flow type.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<BillingPortalUrlResponse>

A promise that resolves to the billing portal URL.

deleteApp()

deleteApp(appId: string, requestId?: string): Promise<boolean>;

Deletes a developer application.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

Promise<boolean>

deleteAppWebhook()

deleteAppWebhook(appId: string, requestId?: string): Promise<boolean>;

Deletes an app webhook configuration.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

Promise<boolean>

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.

If the project is a workspace project, it must have been archived first before it can be deleted, otherwise calling this function will result in an error. Personal projects can be deleted regardless of their archived status.

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.

deleteUiExtension()

deleteUiExtension(uiExtensionId: string, requestId?: string): Promise<boolean>;

Deletes a UI extension.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`uiExtensionId`	`string`
`requestId?`	`string`

Returns

Promise<boolean>

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://files.todoist.com/...'
})

deleteViewOptions()

deleteViewOptions(args: ViewOptionsDeleteArgs, requestId?: string): Promise<void>;

Deletes the saved options for a view.

Parameters

Parameter	Type	Description
`args`	`ViewOptionsDeleteArgs`	The view whose saved options to delete.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<void>

A promise that resolves when the view options are deleted.

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;
  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; 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?: string;
}, requestId?: string): Promise<AllWorkspaceInvitationsResponse>;

Gets all workspace invitations (admin only).

Parameters

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

Returns

Promise<AllWorkspaceInvitationsResponse>

Array of email addresses with pending invitations.

getApp()

getApp(appId: string, requestId?: string): Promise<{
  appTokenScopes: string[] | null;
  clientId: string;
  createdAt: Date;
  description: string | null;
  displayName: string;
  iconLg: string | null;
  iconMd: string | null;
  iconSm: string | null;
  id: string;
  oauthRedirectUri: string | null;
  serviceUrl: string | null;
  status: "public";
  userCount: number;
  userId: string;
}>;

Retrieves a single developer application by ID.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

getAppByDistributionToken()

getAppByDistributionToken(distributionToken: string, requestId?: string): Promise<{
  appTokenScopes: string[] | null;
  description: string | null;
  displayName: string;
  iconMd: string | null;
  id: string;
  uiExtensions: {
     description: string;
     extensionType: "context-menu" | "composer" | "settings";
     icon: string | null;
     name: string;
  }[];
}>;

Resolves a public-facing app view from a distribution token. Used during the installation flow to show prospective installers what the app does and which scopes it requests.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`distributionToken`	`string`
`requestId?`	`string`

Returns

Promise<{ appTokenScopes: string[] | null; description: string | null; displayName: string; iconMd: string | null; id: string; uiExtensions: { description: string; extensionType: "context-menu" | "composer" | "settings"; icon: string | null; name: string; }[]; }>

getAppDistributionToken()

getAppDistributionToken(appId: string, requestId?: string): Promise<{
  distributionToken: string;
}>;

Gets the distribution token for an app, which third parties use to install it.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

Promise<{ distributionToken: string; }>

getAppInstallation()

getAppInstallation(installationId: string, requestId?: string): Promise<{
  appTokenScopesValidated: boolean;
  createdTs: number;
  creator: string;
  id: string;
  installationType: "user";
  integration:   | {
     appTokenScopes: string[] | null;
     clientId: string;
     createdAt: Date;
     description: string | null;
     displayName: string;
     iconLg: string | null;
     iconMd: string | null;
     iconSm: string | null;
     id: string;
     oauthRedirectUri: string | null;
     serviceUrl: string | null;
     status: "public";
     userId: string;
   }
     | null;
}>;

Retrieves a single app installation by ID.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`installationId`	`string`
`requestId?`	`string`

Returns

Promise<{ appTokenScopesValidated: boolean; createdTs: number; creator: string; id: string; installationType: "user"; integration: | { appTokenScopes: string[] | null; clientId: string; createdAt: Date; description: string | null; displayName: string; iconLg: string | null; iconMd: string | null; iconSm: string | null; id: string; oauthRedirectUri: string | null; serviceUrl: string | null; status: "public"; userId: string; } | null; }>

getAppInstallations()

getAppInstallations(requestId?: string): Promise<{
  appTokenScopesValidated: boolean;
  createdTs: number;
  creator: string;
  id: string;
  installationType: "user";
  integration:   | {
     appTokenScopes: string[] | null;
     clientId: string;
     createdAt: Date;
     description: string | null;
     displayName: string;
     iconLg: string | null;
     iconMd: string | null;
     iconSm: string | null;
     id: string;
     oauthRedirectUri: string | null;
     serviceUrl: string | null;
     status: "public";
     userId: string;
   }
     | null;
}[]>;

Lists all apps installed on the authenticated user's account.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`requestId?`	`string`

Returns

getApps()

getApps(requestId?: string): Promise<{
  appTokenScopes: string[] | null;
  clientId: string;
  createdAt: Date;
  description: string | null;
  displayName: string;
  iconLg: string | null;
  iconMd: string | null;
  iconSm: string | null;
  id: string;
  oauthRedirectUri: string | null;
  serviceUrl: string | null;
  status: "public";
  userId: string;
}[]>;

Lists all developer applications owned by the authenticated user.

Requires the dev:app_console scope.

Parameters

Parameter	Type	Description
`requestId?`	`string`	Optional request ID for idempotency.

Returns

A promise that resolves to the list of apps.

getAppSecrets()

getAppSecrets(appId: string, requestId?: string): Promise<{
  clientId: string;
  clientSecret: string;
}>;

Retrieves the OAuth client credentials (client ID and secret) for an app.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

Promise<{ clientId: string; clientSecret: string; }>

getAppTestToken()

getAppTestToken(appId: string, requestId?: string): Promise<{
  accessToken?: string | null;
}>;

Gets the currently issued developer test token for an app (null if none exists).

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

Promise<{ accessToken?: string | null; }>

getAppVerificationToken()

getAppVerificationToken(appId: string, requestId?: string): Promise<{
  verificationToken: string;
}>;

Gets the current webhook verification token for an app.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

Promise<{ verificationToken: string; }>

getAppWebhook()

getAppWebhook(appId: string, requestId?: string): Promise<
  | {
  callbackUrl: string;
  events: (
     | "project:added"
     | "project:updated"
     | "project:deleted"
     | "project:archived"
     | "project:unarchived"
     | "item:added"
     | "item:updated"
     | "item:completed"
     | "item:uncompleted"
     | "item:deleted"
     | "note:added"
     | "note:updated"
     | "note:deleted"
     | "section:added"
     | "section:updated"
     | "section:deleted"
     | "section:archived"
     | "section:unarchived"
     | "label:added"
     | "label:updated"
     | "label:deleted"
     | "filter:added"
     | "filter:updated"
     | "filter:deleted"
    | "reminder:fired")[];
  status: "active" | "invalid";
  version: "1";
}
| null>;

Gets the webhook configuration for an app (null if no webhook is configured).

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

Promise< | { callbackUrl: string; events: ( | "project:added" | "project:updated" | "project:deleted" | "project:archived" | "project:unarchived" | "item:added" | "item:updated" | "item:completed" | "item:uncompleted" | "item:deleted" | "note:added" | "note:updated" | "note:deleted" | "section:added" | "section:updated" | "section:deleted" | "section:archived" | "section:unarchived" | "label:added" | "label:updated" | "label:deleted" | "filter:added" | "filter:updated" | "filter:deleted" | "reminder:fired")[]; status: "active" | "invalid"; version: "1"; } | null>

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: Date;
  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.

getInstalledUiExtensions()

getInstalledUiExtensions(requestId?: string): Promise<(
  | {
  contextType: "task" | "project";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "context-menu";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  composerType: "task" | "comment";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "composer";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "settings";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
})[]>;

Lists UI extensions available (installed) in the web client for the current user.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`requestId?`	`string`

Returns

Promise<( | { contextType: "task" | "project"; defVersion: number; description: string; extensionId: string; extensionType: "context-menu"; height: number | null; icon: string | null; id: string; integrationId: string; minimumCardistVersion: string; name: string; url: string; width: number | null; } | { composerType: "task" | "comment"; defVersion: number; description: string; extensionId: string; extensionType: "composer"; height: number | null; icon: string | null; id: string; integrationId: string; minimumCardistVersion: string; name: string; url: string; width: number | null; } | { defVersion: number; description: string; extensionId: string; extensionType: "settings"; height: number | null; icon: string | null; id: string; integrationId: string; minimumCardistVersion: string; name: string; url: string; width: number | null; })[]>

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.

getPrices()

getPrices(): Promise<{
  pro: {
     billingCycle: "monthly" | "yearly";
     prices: {
        currency: string;
        taxBehavior: "inclusive" | "exclusive" | "unspecified";
        unitAmount: number;
     }[];
  }[];
  teams: {
     billingCycle: "monthly" | "yearly";
     prices: {
        currency: string;
        taxBehavior: "inclusive" | "exclusive" | "unspecified";
        unitAmount: number;
     }[];
  }[];
}>;

Retrieves available Pro and Teams prices.

Requires the billing:read scope.

Returns

Promise<{ pro: { billingCycle: "monthly" | "yearly"; prices: { currency: string; taxBehavior: "inclusive" | "exclusive" | "unspecified"; unitAmount: number; }[]; }[]; teams: { billingCycle: "monthly" | "yearly"; prices: { currency: string; taxBehavior: "inclusive" | "exclusive" | "unspecified"; unitAmount: number; }[]; }[]; }>

A promise that resolves to the available prices.

getPricing()

getPricing(args?: GetPricingArgs): Promise<{
[key: string]: Record<string, Record<string, {
  monthly: string | number;
  yearly: string | number;
}>>;
  latestBiz: string;
  latestPro: string;
  sessionBiz: string;
  sessionPro: string;
}>;

Retrieves pricing information.

Requires the billing:read scope.

Parameters

Parameter	Type	Description
`args?`	`GetPricingArgs`	Optional flag to request formatted pricing.

Returns

Promise<{ [key: string]: Record<string, Record<string, { monthly: string | number; yearly: string | number; }>>; latestBiz: string; latestPro: string; sessionBiz: string; sessionPro: string; }>

A promise that resolves to current and legacy pricing keyed by version.

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: (
        | "Monday"
        | "Tuesday"
        | "Wednesday"
        | "Thursday"
        | "Friday"
        | "Saturday"
       | "Sunday")[];
     karmaDisabled: boolean;
     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: boolean;
     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: ( | "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday")[]; karmaDisabled: boolean; 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: boolean; 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: Date | 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: Date | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: Date | 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: Date | 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";
  updatedAt?: Date | 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: Date | null;
     completedByUid: string | null;
     content: string;
     createdAt: Date;
     deadline?: string | null;
     due?: string | null;
     id: string;
     isCompleted: boolean;
     labels: string[];
     priority: string;
     updatedAt: Date;
  }[];
}>;

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: Date | null; completedByUid: string | null; content: string; createdAt: Date; deadline?: string | null; due?: string | null; id: string; isCompleted: boolean; labels: string[]; priority: string; updatedAt: Date; }[]; }>

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.

getProPlanDetails()

getProPlanDetails(): Promise<{
  currentPlanStatus: "Active" | "Downgraded" | "Cancelled" | "NeverSubscribed";
  downgradeAt: string | null;
  priceList: {
     billingCycle: "monthly" | "yearly";
     prices: {
        currency: string;
        taxBehavior: "inclusive" | "exclusive" | "unspecified";
        unitAmount: number;
     }[];
  }[];
}>;

Retrieves the current user's Pro plan and billing details.

Requires the billing:read scope.

Returns

Promise<{ currentPlanStatus: "Active" | "Downgraded" | "Cancelled" | "NeverSubscribed"; downgradeAt: string | null; priceList: { billingCycle: "monthly" | "yearly"; prices: { currency: string; taxBehavior: "inclusive" | "exclusive" | "unspecified"; unitAmount: number; }[]; }[]; }>

A promise that resolves to the Pro plan details.

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: Date;
  archivedAt: Date | null;
  description: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: Date;
  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.

getSubscriptionInfo()

getSubscriptionInfo(): Promise<{
  activationMethod: "manual" | "stripe" | "appstore" | "playstore" | "teams";
  billingPortalSwitchToAnnualUrl: string | null;
  billingPortalUrl: string | null;
  expirationDate: string | null;
  hasBillingPortal: boolean;
  hasBillingPortalSwitchToAnnual: boolean;
  hasSwitchLegacyToCurrent: boolean;
  invoiceCreditBalance: Record<string, number> | null;
  plan: "free" | "pro" | "pro_gifted" | "pro_legacy";
  planPrice:   | {
     amount: string;
     billingCycle: "monthly" | "yearly" | null;
     currency: string;
     rawAmount: number;
     taxBehavior: "inclusive" | "exclusive" | "unspecified";
   }
     | null;
  status:   | "none"
     | "autorenew"
     | "canceled"
     | "expired"
     | "trial"
     | "trial_canceled";
}>;

Retrieves the current user's subscription state.

Requires the billing:read scope.

Returns

Promise<{ activationMethod: "manual" | "stripe" | "appstore" | "playstore" | "teams"; billingPortalSwitchToAnnualUrl: string | null; billingPortalUrl: string | null; expirationDate: string | null; hasBillingPortal: boolean; hasBillingPortalSwitchToAnnual: boolean; hasSwitchLegacyToCurrent: boolean; invoiceCreditBalance: Record<string, number> | null; plan: "free" | "pro" | "pro_gifted" | "pro_legacy"; planPrice: | { amount: string; billingCycle: "monthly" | "yearly" | null; currency: string; rawAmount: number; taxBehavior: "inclusive" | "exclusive" | "unspecified"; } | null; status: | "none" | "autorenew" | "canceled" | "expired" | "trial" | "trial_canceled"; }>

A promise that resolves to the user's subscription info.

getTask()

getTask(id: string): Promise<{
  addedAt: Date | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: Date | 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: Date | 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.

getUiExtension()

getUiExtension(uiExtensionId: string, requestId?: string): Promise<
  | {
  contextType: "task" | "project";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "context-menu";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  composerType: "task" | "comment";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "composer";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "settings";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}>;

Retrieves a single UI extension by ID.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`uiExtensionId`	`string`
`requestId?`	`string`

Returns

getUiExtensionsForApp()

getUiExtensionsForApp(appId: string, requestId?: string): Promise<(
  | {
  contextType: "task" | "project";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "context-menu";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  composerType: "task" | "comment";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "composer";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "settings";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
})[]>;

Lists all UI extensions belonging to a given app (integration).

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

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;
  };
  websocketUrl?: 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; }; websocketUrl?: string; weekendStartDay: number; weeklyGoal: number; }>

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

getUserAuthorizations()

getUserAuthorizations(requestId?: string): Promise<{
  accessTokenId: string;
  app:   | {
     description: string | null;
     displayName: string;
     iconMd: string | null;
     id: string;
     serviceUrl: string | null;
   }
     | null;
  createdAt: Date;
  scope: string[];
  scopeDescriptions: string[];
}[]>;

Lists all apps the user has authorized (granted a token to).

Requires the dev:app_console scope.

Parameters

Parameter	Type
`requestId?`	`string`

Returns

Promise<{ accessTokenId: string; app: | { description: string | null; displayName: string; iconMd: string | null; id: string; serviceUrl: string | null; } | null; createdAt: Date; scope: string[]; scopeDescriptions: string[]; }[]>

getViewOptions()

getViewOptions(): Promise<{
[key: string]: unknown;
  calendarSettings?:   | {
   [key: string]: unknown;
     color?: "PROJECT" | "LABEL" | "PRIORITY" | null;
     layout?: "WEEK" | "MONTH" | null;
     visibleDayCount?: 3 | 1 | 7 | null;
   }
     | null;
  filteredBy?: string | null;
  groupedBy?:   | "PROJECT"
     | "LABEL"
     | "ASSIGNEE"
     | "ADDED_DATE"
     | "DUE_DATE"
     | "DEADLINE"
     | "PRIORITY"
     | "WORKSPACE"
     | null;
  isDeleted?: boolean;
  objectId?: string | null;
  showCompletedTasks?: boolean;
  sortedBy?:   | "PROJECT"
     | "ASSIGNEE"
     | "ADDED_DATE"
     | "DUE_DATE"
     | "DEADLINE"
     | "PRIORITY"
     | "WORKSPACE"
     | "MANUAL"
     | "ALPHABETICALLY"
     | null;
  sortOrder?: "ASC" | "DESC" | null;
  viewMode?: "LIST" | "BOARD" | "CALENDAR" | null;
  viewType:   | "PROJECT"
     | "TODAY"
     | "UPCOMING"
     | "LABEL"
     | "FILTER"
     | "WORKSPACE_FILTER"
     | "SEARCH"
     | "TEMPLATE_PREVIEW"
     | "TASK_DETAIL"
     | "AUTOMATION"
     | "ASSIGNED"
     | "OVERDUE"
     | "WORKSPACE_OVERVIEW";
}[]>;

Retrieves the authenticated user's active saved view options.

Returns

Promise<{ [key: string]: unknown; calendarSettings?: | { [key: string]: unknown; color?: "PROJECT" | "LABEL" | "PRIORITY" | null; layout?: "WEEK" | "MONTH" | null; visibleDayCount?: 3 | 1 | 7 | null; } | null; filteredBy?: string | null; groupedBy?: | "PROJECT" | "LABEL" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | null; isDeleted?: boolean; objectId?: string | null; showCompletedTasks?: boolean; sortedBy?: | "PROJECT" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | "MANUAL" | "ALPHABETICALLY" | null; sortOrder?: "ASC" | "DESC" | null; viewMode?: "LIST" | "BOARD" | "CALENDAR" | null; viewType: | "PROJECT" | "TODAY" | "UPCOMING" | "LABEL" | "FILTER" | "WORKSPACE_FILTER" | "SEARCH" | "TEMPLATE_PREVIEW" | "TASK_DETAIL" | "AUTOMATION" | "ASSIGNED" | "OVERDUE" | "WORKSPACE_OVERVIEW"; }[]>

A promise that resolves to the active saved view options.

getWorkspace()

getWorkspace(id: string, requestId?: string): Promise<{
  createdAt: Date | 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<{
  projectInsights: {
     health:   | {
        description?: string | null;
        descriptionSummary?: string | null;
        isStale: boolean;
        projectId?: string | null;
        status: "UNKNOWN" | "ON_TRACK" | "AT_RISK" | "CRITICAL" | "EXCELLENT" | "ERROR";
        updatedAt?: Date | 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<{ projectInsights: { health: | { description?: string | null; descriptionSummary?: string | null; isStale: boolean; projectId?: string | null; status: "UNKNOWN" | "ON_TRACK" | "AT_RISK" | "CRITICAL" | "EXCELLENT" | "ERROR"; updatedAt?: Date | 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: string;
}>;

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: string; }>

Workspace plan details.

getWorkspaces()

getWorkspaces(requestId?: string): Promise<{
  createdAt: Date | 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.

installApp()

installApp(args: InstallAppArgs, requestId?: string): Promise<{
  appTokenScopesValidated: boolean;
  createdTs: number;
  creator: string;
  id: string;
  installationType: "user";
  integration:   | {
     appTokenScopes: string[] | null;
     clientId: string;
     createdAt: Date;
     description: string | null;
     displayName: string;
     iconLg: string | null;
     iconMd: string | null;
     iconSm: string | null;
     id: string;
     oauthRedirectUri: string | null;
     serviceUrl: string | null;
     status: "public";
     userId: string;
   }
     | null;
}>;

Installs an application via its distribution token.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`args`	`InstallAppArgs`
`requestId?`	`string`

Returns

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: Date | 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: Date | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: Date | 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: Date | 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: Date | 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: Date | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: Date | 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: Date | 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: Date | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: Date | 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: Date | 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: Date | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: Date | 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: Date | 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: Date | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: Date | 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: Date | 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.

reactivatePlan()

reactivatePlan(requestId?: string): Promise<{
  activationMethod: "manual" | "stripe" | "appstore" | "playstore" | "teams";
  billingPortalSwitchToAnnualUrl: string | null;
  billingPortalUrl: string | null;
  expirationDate: string | null;
  hasBillingPortal: boolean;
  hasBillingPortalSwitchToAnnual: boolean;
  hasSwitchLegacyToCurrent: boolean;
  invoiceCreditBalance: Record<string, number> | null;
  plan: "free" | "pro" | "pro_gifted" | "pro_legacy";
  planPrice:   | {
     amount: string;
     billingCycle: "monthly" | "yearly" | null;
     currency: string;
     rawAmount: number;
     taxBehavior: "inclusive" | "exclusive" | "unspecified";
   }
     | null;
  status:   | "none"
     | "autorenew"
     | "canceled"
     | "expired"
     | "trial"
     | "trial_canceled";
}>;

Reactivates a previously canceled subscription.

Requires the billing:read_write scope.

Parameters

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

Returns

A promise that resolves to the fresh subscription info after reactivation.

rejectWorkspaceInvitation()

rejectWorkspaceInvitation(args: WorkspaceInvitationActionArgs, requestId?: string): Promise<{
  id: string;
  inviterId: string;
  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; 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.

resetAppClientSecret()

resetAppClientSecret(appId: string, requestId?: string): Promise<{
  appTokenScopes: string[] | null;
  clientId: string;
  createdAt: Date;
  description: string | null;
  displayName: string;
  iconLg: string | null;
  iconMd: string | null;
  iconSm: string | null;
  id: string;
  oauthRedirectUri: string | null;
  serviceUrl: string | null;
  status: "public";
  userCount: number;
  userId: string;
}>;

Rotates the app's OAuth client secret, returning the updated app record.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

resetAppVerificationToken()

resetAppVerificationToken(appId: string, requestId?: string): Promise<{
  verificationToken: string;
}>;

Resets the webhook verification token for an app, returning the new value.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

Promise<{ verificationToken: string; }>

revokeAppTokens()

revokeAppTokens(appId: string, requestId?: string): Promise<{
  appTokenScopes: string[] | null;
  clientId: string;
  createdAt: Date;
  description: string | null;
  displayName: string;
  iconLg: string | null;
  iconMd: string | null;
  iconSm: string | null;
  id: string;
  oauthRedirectUri: string | null;
  serviceUrl: string | null;
  status: "public";
  userCount: number;
  userId: string;
}>;

Revokes every access token issued for the given app.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`requestId?`	`string`

Returns

revokeUserAuthorization()

revokeUserAuthorization(args: RevokeUserAuthorizationArgs, requestId?: string): Promise<boolean>;

Revokes a specific user authorization (access token granted to a third-party app).

Requires the dev:app_console scope.

Parameters

Parameter	Type
`args`	`RevokeUserAuthorizationArgs`
`requestId?`	`string`

Returns

Promise<boolean>

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.

setViewOptions()

setViewOptions(args: ViewOptionsSetArgs, requestId?: string): Promise<void>;

Sets saved options for a view.

Parameters

Parameter	Type	Description
`args`	`ViewOptionsSetArgs`	The saved view options to set.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<void>

A promise that resolves when the view options are saved.

startProTrial()

startProTrial(args: CheckoutArgs, requestId?: string): Promise<CheckoutSessionResponse>;

Creates a Stripe checkout session to start a Pro trial.

Requires the billing:read_write scope.

Parameters

Parameter	Type	Description
`args`	`CheckoutArgs`	Currency, billing cycle, and redirect URLs.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<CheckoutSessionResponse>

A promise that resolves to the checkout session URL.

startWorkspaceTrial()

startWorkspaceTrial(args: StartWorkspaceTrialArgs, requestId?: string): Promise<CheckoutSessionResponse>;

Creates a Stripe checkout session to start a workspace trial.

Requires the billing:read_write scope.

Parameters

Parameter	Type	Description
`args`	`StartWorkspaceTrialArgs`	Workspace ID, currency, billing cycle, and redirect URLs.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<CheckoutSessionResponse>

A promise that resolves to the checkout session URL.

sync()

sync(syncRequest: SyncRequest, requestId?: string): Promise<{
[key: string]: unknown;
  calendarAccounts?: {
   [key: string]: unknown;
     calendarsSyncState?: "error" | "synced" | "syncing";
     id: string;
     isAllDayTasksEnabled?: boolean;
     isDeleted?: boolean;
     isEventsEnabled?: boolean;
     isTasksEnabled?: boolean;
     name: string;
     pendingOperationUntil?: string | null;
     type: "google" | "microsoft" | "apple";
  }[];
  calendars?: {
   [key: string]: unknown;
     accountId: string;
     color: string | null;
     id: string;
     isTaskCalendar?: boolean;
     isVisible: boolean;
     summary: string;
  }[];
  collaborators?: {
   [key: string]: unknown;
     email: string;
     fullName: string;
     id: string;
     imageId: string | null;
     timezone: string;
  }[];
  collaboratorStates?: {
   [key: string]: unknown;
     isDeleted: boolean;
     projectId: string;
     state: "active" | "invited";
     userId: string;
     workspaceRole?: "ADMIN" | "MEMBER" | "GUEST";
  }[];
  completedInfo?: (
     | {
   [key: string]: unknown;
     archivedSections: number;
     completedItems: number;
     projectId: string;
   }
     | {
   [key: string]: unknown;
     completedItems: number;
     id: string;
     sectionId: string;
   }
     | {
   [key: string]: unknown;
     completedItems: number;
     id?: string;
     itemId: string;
  })[];
  dayOrders?: Record<string, number>;
  filters?: {
   [key: string]: unknown;
     color: string;
     description?: string | null;
     id: string;
     isDeleted: boolean;
     isFavorite: boolean;
     isFrozen: boolean;
     itemOrder: number;
     name: string;
     query: string;
  }[];
  folders?: {
   [key: string]: unknown;
     childOrder: number;
     defaultOrder: number;
     id: string;
     isDeleted: boolean;
     name: string;
     workspaceId: string;
  }[];
  fullSync?: boolean;
  items?: {
     addedAt: Date | null;
     addedByUid: string | null;
     assignedByUid: string | null;
     checked: boolean;
     childOrder: number;
     completedAt: Date | 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: Date | null;
     url: string;
     userId: string;
  }[];
  labels?: {
     color: string;
     id: string;
     isDeleted?: boolean;
     isFavorite: boolean;
     name: string;
     order?: number | null;
  }[];
  liveNotifications?: {
   [key: string]: unknown;
     assignedByUid?: string | null;
     createdAt: Date;
     fromUid?: string;
     fromUser?: {
        email: string;
        fullName: string;
        id: string;
        imageId: string | null;
     };
     id: string;
     invitationId?: string;
     invitationSecret?: string;
     isDeleted?: boolean;
     isUnread: boolean;
     itemContent?: string;
     itemId?: string;
     notificationType: string;
     projectId?: string;
     projectName?: string;
     responsibleUid?: string | null;
  }[];
  locations?: Record<string, unknown>[];
  notes?: {
   [key: string]: unknown;
     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;
     itemId?: string;
     postedAt: Date;
     postedUid: string;
     projectId?: string;
     reactions: Record<string, string[]> | null;
     uidsToNotify: string[] | null;
  }[];
  notificationSettings?: Record<string, boolean>;
  projectNotes?: {
   [key: string]: unknown;
     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;
     itemId?: string;
     postedAt: Date;
     postedUid: string;
     projectId?: string;
     reactions: Record<string, string[]> | null;
     uidsToNotify: string[] | null;
  }[];
  projects?: (
     | {
     canAssignTasks: boolean;
     childOrder: number;
     color: string;
     createdAt: Date | 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: Date | null;
     url: string;
     viewStyle: string;
   }
     | {
     access?: {
        visibility: "restricted" | "team" | "public";
     };
     canAssignTasks: boolean;
     childOrder: number;
     collaboratorRoleDefault: string;
     color: string;
     createdAt: Date | 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: Date | null;
     url: string;
     viewStyle: string;
     workspaceId: string;
  })[];
  projectViewOptionsDefaults?: {
   [key: string]: unknown;
     calendarSettings?:   | {
      [key: string]: unknown;
        color?: "PROJECT" | "LABEL" | "PRIORITY" | null;
        layout?: "WEEK" | "MONTH" | null;
        visibleDayCount?: 3 | 1 | 7 | null;
      }
        | null;
     filteredBy?: string | null;
     groupedBy?:   | "PROJECT"
        | "LABEL"
        | "ASSIGNEE"
        | "ADDED_DATE"
        | "DUE_DATE"
        | "DEADLINE"
        | "PRIORITY"
        | "WORKSPACE"
        | null;
     projectId: string;
     showCompletedTasks?: boolean;
     sortedBy?:   | "PROJECT"
        | "ASSIGNEE"
        | "ADDED_DATE"
        | "DUE_DATE"
        | "DEADLINE"
        | "PRIORITY"
        | "WORKSPACE"
        | "MANUAL"
        | "ALPHABETICALLY"
        | null;
     sortOrder?: "ASC" | "DESC" | null;
     viewMode?: "LIST" | "BOARD" | "CALENDAR" | null;
  }[];
  reminders?: (
     | {
   [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;
      }
        | 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;
      }
        | null;
     id: string;
     isDeleted: boolean;
     isUrgent?: boolean;
     itemId: string;
     minuteOffset: number;
     notifyUid: string;
     projectId?: string;
     type: "relative";
  })[];
  remindersLocation?: {
   [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";
  }[];
  roleActions?: Record<string, unknown>[];
  sections?: {
     addedAt: Date;
     archivedAt: Date | null;
     description: string | null;
     id: string;
     isArchived: boolean;
     isCollapsed: boolean;
     isDeleted: boolean;
     name: string;
     projectId: string;
     sectionOrder: number;
     updatedAt: Date;
     url: string;
     userId: string;
  }[];
  stats?: Record<string, unknown>;
  suggestions?: (
     | {
   [key: string]: unknown;
     content: {
        locale: string;
        templates: {
         [key: string]: unknown;
           id: string;
           name: string;
           templateType: "project" | "setup";
        }[];
     };
     isDeleted: boolean;
     type: "templates" | "most_used_user_templates";
   }
     | {
   [key: string]: unknown;
     content: {
        locale: string;
        templates: {
         [key: string]: unknown;
           id: string;
           name: string;
           templateType: "project" | "setup";
           workspaceId: string | null;
        }[];
     };
     isDeleted: boolean;
     type: "most_used_workspace_templates";
  })[];
  syncStatus?: Record<string, 
     | {
     error: string;
     errorCode: number;
     errorExtra: Record<string, unknown>;
     errorTag: string;
     httpCode: number;
   }
    | "ok">;
  syncToken?: string;
  tempIdMapping?: Record<string, string>;
  tooltips?: {
   [key: string]: unknown;
     scheduled?: string[];
     seen?: string[];
  };
  user?: {
   [key: string]: unknown;
     activatedUser: boolean;
     autoReminder: number;
     avatarBig?: string;
     avatarMedium?: string;
     avatarS640?: string;
     avatarSmall?: string;
     businessAccountId: string | null;
     dailyGoal: number;
     dateFormat: "DD/MM/YYYY" | "MM/DD/YYYY";
     dateistLang?: string | null;
     daysOff: number[];
     email: string;
     featureIdentifier: string;
     features: {
      [key: string]: unknown;
        autoInviteDisabled?: boolean;
        beta: boolean;
        dateistInlineDisabled: boolean;
        dateistLang: any;
        goldTheme?: boolean;
        hasPushReminders: boolean;
        karmaDisabled: boolean;
        karmaVacation: boolean;
        migratedFromTdb?: boolean;
        restriction: number;
     };
     freeTrailExpires?: Date;
     fullName: string;
     gettingStartedGuideProjects:   | {
      [key: string]: unknown;
        closed: boolean;
        completed: boolean;
        onboardingUseCase: string;
        projectId: string;
      }[]
        | null;
     hasMagicNumber: boolean;
     hasPassword: boolean;
     hasStartedATrial?: boolean;
     id: string;
     imageId: string | null;
     inboxProjectId: string;
     isCelebrationsEnabled: boolean;
     isPremium: boolean;
     joinableWorkspace:   | {
      [key: string]: unknown;
        memberCount: number;
        workspaceId: string;
        workspaceName: string;
      }
        | null;
     joinedAt: Date;
     karma: number;
     karmaTrend: string;
     lang: string;
     mfaEnabled?: boolean;
     mobileHost?: string | null;
     mobileNumber?: string | null;
     nextWeek:   | "Monday"
        | "Tuesday"
        | "Wednesday"
        | "Thursday"
        | "Friday"
        | "Saturday"
        | "Sunday";
     onboardingCompleted?: boolean | null;
     onboardingInitiated?: boolean | null;
     onboardingLevel?: string | null;
     onboardingPersona?: string | null;
     onboardingRole?: string | null;
     onboardingSkipped?: boolean;
     onboardingTeamMode?: boolean | null;
     onboardingUseCases?: string[] | null;
     premiumStatus:   | "not_premium"
        | "current_personal_plan"
        | "legacy_personal_plan"
        | "teams_business_member";
     premiumUntil: Date | null;
     rambleSessionsUsage?:   | {
        currentCount: number;
        limit: number;
        remaining: number;
        resetDate: Date;
      }
        | null;
     shareLimit: number;
     sortOrder: number;
     startDay:   | "Monday"
        | "Tuesday"
        | "Wednesday"
        | "Thursday"
        | "Friday"
        | "Saturday"
        | "Sunday";
     startPage: string;
     themeId: string;
     timeFormat: "24h" | "12h";
     token?: string;
     tzInfo: {
      [key: string]: unknown;
        gmtString: string;
        hours: number;
        isDst: boolean;
        minutes: number;
        timezone: string;
     };
     uniquePrefix: number;
     verificationStatus: string;
     websocketUrl: string;
     weekendStartDay: number;
     weeklyGoal: number;
  };
  userPlanLimits?: {
   [key: string]: unknown;
     current: {
      [key: string]: unknown;
        activeProjects?: number;
        activityLog?: number;
        collaboratorsPerProject?: number;
        commentsPerTask?: number;
        fileUploadsPerComment?: number;
        filtersPerUser?: number;
        labelsPerTask?: number;
        remindersPerUser?: number;
        sectionsPerProject?: number;
        tasksPerProject?: number;
     };
     next:   | {
      [key: string]: unknown;
        activeProjects?: number;
        activityLog?: number;
        collaboratorsPerProject?: number;
        commentsPerTask?: number;
        fileUploadsPerComment?: number;
        filtersPerUser?: number;
        labelsPerTask?: number;
        remindersPerUser?: number;
        sectionsPerProject?: number;
        tasksPerProject?: number;
      }
        | null;
  };
  userSettings?: {
   [key: string]: unknown;
     aiEmailAssist: boolean;
     completedSoundDesktop: boolean;
     completedSoundMobile: boolean;
     debugLogSendingEnabledUntil?: string | null;
     legacyPricing: boolean;
     navigation: {
      [key: string]: unknown;
        countsShown: boolean;
        features: {
           name: string;
           shown: boolean;
        }[];
     };
     quickAdd: {
      [key: string]: unknown;
        features: {
           name: string;
           shown: boolean;
        }[];
        labelsShown: boolean;
     };
     reminderDesktop: boolean;
     reminderEmail: boolean;
     reminderPush: boolean;
     resetRecurringSubtasks: boolean;
     syncTheme?: boolean;
     theme?: string | null;
  };
  viewOptions?: {
   [key: string]: unknown;
     calendarSettings?:   | {
      [key: string]: unknown;
        color?: "PROJECT" | "LABEL" | "PRIORITY" | null;
        layout?: "WEEK" | "MONTH" | null;
        visibleDayCount?: 3 | 1 | 7 | null;
      }
        | null;
     filteredBy?: string | null;
     groupedBy?:   | "PROJECT"
        | "LABEL"
        | "ASSIGNEE"
        | "ADDED_DATE"
        | "DUE_DATE"
        | "DEADLINE"
        | "PRIORITY"
        | "WORKSPACE"
        | null;
     isDeleted?: boolean;
     objectId?: string | null;
     showCompletedTasks?: boolean;
     sortedBy?:   | "PROJECT"
        | "ASSIGNEE"
        | "ADDED_DATE"
        | "DUE_DATE"
        | "DEADLINE"
        | "PRIORITY"
        | "WORKSPACE"
        | "MANUAL"
        | "ALPHABETICALLY"
        | null;
     sortOrder?: "ASC" | "DESC" | null;
     viewMode?: "LIST" | "BOARD" | "CALENDAR" | null;
     viewType:   | "PROJECT"
        | "TODAY"
        | "UPCOMING"
        | "LABEL"
        | "FILTER"
        | "WORKSPACE_FILTER"
        | "SEARCH"
        | "TEMPLATE_PREVIEW"
        | "TASK_DETAIL"
        | "AUTOMATION"
        | "ASSIGNED"
        | "OVERDUE"
        | "WORKSPACE_OVERVIEW";
  }[];
  workspaceFilters?: {
   [key: string]: unknown;
     color: string;
     createdAt: Date;
     creatorUid: string;
     description?: string | null;
     id: string;
     isDeleted: boolean;
     isFavorite: boolean;
     isFrozen: boolean;
     itemOrder: number;
     name: string;
     query: string;
     updatedAt: Date;
     updaterUid: string;
     workspaceId: string;
  }[];
  workspaces?: {
     adminSortingApplied: boolean;
     createdAt: Date | undefined;
     creatorId: string;
     currentActiveProjects: number | null;
     currentMemberCount: number | null;
     currentTemplateCount: number | null;
     defaultCollaborators?: {
        predefinedGroupIds: string[];
        userIds: string[];
     };
     description: string;
     domainDiscovery?: boolean | null;
     domainName?: string | null;
     id: string;
     inviteCode?: string | null;
     isCollapsed: boolean;
     isDeleted: boolean;
     isGuestAllowed?: boolean | null;
     isLinkSharingEnabled?: boolean | null;
     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;
     memberCountByType?: {
        adminCount: number;
        guestCount: number;
        memberCount: number;
     };
     name: string;
     pendingInvitations?: string[] | null;
     plan: "STARTER" | "BUSINESS";
     projectSortPreference?: string | null;
     properties?: Record<string, unknown>;
     restrictEmailDomains?: boolean | null;
     role?: "ADMIN" | "MEMBER" | "GUEST";
  }[];
  workspaceUsers?: {
     fullName: string;
     imageId: string | null;
     isDeleted: boolean;
     role: "ADMIN" | "MEMBER" | "GUEST";
     timezone: string;
     userEmail: string;
     userId: string;
     workspaceId: string;
  }[];
}>;

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<{ [key: string]: unknown; calendarAccounts?: { [key: string]: unknown; calendarsSyncState?: "error" | "synced" | "syncing"; id: string; isAllDayTasksEnabled?: boolean; isDeleted?: boolean; isEventsEnabled?: boolean; isTasksEnabled?: boolean; name: string; pendingOperationUntil?: string | null; type: "google" | "microsoft" | "apple"; }[]; calendars?: { [key: string]: unknown; accountId: string; color: string | null; id: string; isTaskCalendar?: boolean; isVisible: boolean; summary: string; }[]; collaborators?: { [key: string]: unknown; email: string; fullName: string; id: string; imageId: string | null; timezone: string; }[]; collaboratorStates?: { [key: string]: unknown; isDeleted: boolean; projectId: string; state: "active" | "invited"; userId: string; workspaceRole?: "ADMIN" | "MEMBER" | "GUEST"; }[]; completedInfo?: ( | { [key: string]: unknown; archivedSections: number; completedItems: number; projectId: string; } | { [key: string]: unknown; completedItems: number; id: string; sectionId: string; } | { [key: string]: unknown; completedItems: number; id?: string; itemId: string; })[]; dayOrders?: Record<string, number>; filters?: { [key: string]: unknown; color: string; description?: string | null; id: string; isDeleted: boolean; isFavorite: boolean; isFrozen: boolean; itemOrder: number; name: string; query: string; }[]; folders?: { [key: string]: unknown; childOrder: number; defaultOrder: number; id: string; isDeleted: boolean; name: string; workspaceId: string; }[]; fullSync?: boolean; items?: { addedAt: Date | null; addedByUid: string | null; assignedByUid: string | null; checked: boolean; childOrder: number; completedAt: Date | 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: Date | null; url: string; userId: string; }[]; labels?: { color: string; id: string; isDeleted?: boolean; isFavorite: boolean; name: string; order?: number | null; }[]; liveNotifications?: { [key: string]: unknown; assignedByUid?: string | null; createdAt: Date; fromUid?: string; fromUser?: { email: string; fullName: string; id: string; imageId: string | null; }; id: string; invitationId?: string; invitationSecret?: string; isDeleted?: boolean; isUnread: boolean; itemContent?: string; itemId?: string; notificationType: string; projectId?: string; projectName?: string; responsibleUid?: string | null; }[]; locations?: Record<string, unknown>[]; notes?: { [key: string]: unknown; 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; itemId?: string; postedAt: Date; postedUid: string; projectId?: string; reactions: Record<string, string[]> | null; uidsToNotify: string[] | null; }[]; notificationSettings?: Record<string, boolean>; projectNotes?: { [key: string]: unknown; 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; itemId?: string; postedAt: Date; postedUid: string; projectId?: string; reactions: Record<string, string[]> | null; uidsToNotify: string[] | null; }[]; projects?: ( | { canAssignTasks: boolean; childOrder: number; color: string; createdAt: Date | 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: Date | null; url: string; viewStyle: string; } | { access?: { visibility: "restricted" | "team" | "public"; }; canAssignTasks: boolean; childOrder: number; collaboratorRoleDefault: string; color: string; createdAt: Date | 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: Date | null; url: string; viewStyle: string; workspaceId: string; })[]; projectViewOptionsDefaults?: { [key: string]: unknown; calendarSettings?: | { [key: string]: unknown; color?: "PROJECT" | "LABEL" | "PRIORITY" | null; layout?: "WEEK" | "MONTH" | null; visibleDayCount?: 3 | 1 | 7 | null; } | null; filteredBy?: string | null; groupedBy?: | "PROJECT" | "LABEL" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | null; projectId: string; showCompletedTasks?: boolean; sortedBy?: | "PROJECT" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | "MANUAL" | "ALPHABETICALLY" | null; sortOrder?: "ASC" | "DESC" | null; viewMode?: "LIST" | "BOARD" | "CALENDAR" | null; }[]; reminders?: ( | { [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; } | 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; } | null; id: string; isDeleted: boolean; isUrgent?: boolean; itemId: string; minuteOffset: number; notifyUid: string; projectId?: string; type: "relative"; })[]; remindersLocation?: { [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"; }[]; roleActions?: Record<string, unknown>[]; sections?: { addedAt: Date; archivedAt: Date | null; description: string | null; id: string; isArchived: boolean; isCollapsed: boolean; isDeleted: boolean; name: string; projectId: string; sectionOrder: number; updatedAt: Date; url: string; userId: string; }[]; stats?: Record<string, unknown>; suggestions?: ( | { [key: string]: unknown; content: { locale: string; templates: { [key: string]: unknown; id: string; name: string; templateType: "project" | "setup"; }[]; }; isDeleted: boolean; type: "templates" | "most_used_user_templates"; } | { [key: string]: unknown; content: { locale: string; templates: { [key: string]: unknown; id: string; name: string; templateType: "project" | "setup"; workspaceId: string | null; }[]; }; isDeleted: boolean; type: "most_used_workspace_templates"; })[]; syncStatus?: Record<string, | { error: string; errorCode: number; errorExtra: Record<string, unknown>; errorTag: string; httpCode: number; } | "ok">; syncToken?: string; tempIdMapping?: Record<string, string>; tooltips?: { [key: string]: unknown; scheduled?: string[]; seen?: string[]; }; user?: { [key: string]: unknown; activatedUser: boolean; autoReminder: number; avatarBig?: string; avatarMedium?: string; avatarS640?: string; avatarSmall?: string; businessAccountId: string | null; dailyGoal: number; dateFormat: "DD/MM/YYYY" | "MM/DD/YYYY"; dateistLang?: string | null; daysOff: number[]; email: string; featureIdentifier: string; features: { [key: string]: unknown; autoInviteDisabled?: boolean; beta: boolean; dateistInlineDisabled: boolean; dateistLang: any; goldTheme?: boolean; hasPushReminders: boolean; karmaDisabled: boolean; karmaVacation: boolean; migratedFromTdb?: boolean; restriction: number; }; freeTrailExpires?: Date; fullName: string; gettingStartedGuideProjects: | { [key: string]: unknown; closed: boolean; completed: boolean; onboardingUseCase: string; projectId: string; }[] | null; hasMagicNumber: boolean; hasPassword: boolean; hasStartedATrial?: boolean; id: string; imageId: string | null; inboxProjectId: string; isCelebrationsEnabled: boolean; isPremium: boolean; joinableWorkspace: | { [key: string]: unknown; memberCount: number; workspaceId: string; workspaceName: string; } | null; joinedAt: Date; karma: number; karmaTrend: string; lang: string; mfaEnabled?: boolean; mobileHost?: string | null; mobileNumber?: string | null; nextWeek: | "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"; onboardingCompleted?: boolean | null; onboardingInitiated?: boolean | null; onboardingLevel?: string | null; onboardingPersona?: string | null; onboardingRole?: string | null; onboardingSkipped?: boolean; onboardingTeamMode?: boolean | null; onboardingUseCases?: string[] | null; premiumStatus: | "not_premium" | "current_personal_plan" | "legacy_personal_plan" | "teams_business_member"; premiumUntil: Date | null; rambleSessionsUsage?: | { currentCount: number; limit: number; remaining: number; resetDate: Date; } | null; shareLimit: number; sortOrder: number; startDay: | "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"; startPage: string; themeId: string; timeFormat: "24h" | "12h"; token?: string; tzInfo: { [key: string]: unknown; gmtString: string; hours: number; isDst: boolean; minutes: number; timezone: string; }; uniquePrefix: number; verificationStatus: string; websocketUrl: string; weekendStartDay: number; weeklyGoal: number; }; userPlanLimits?: { [key: string]: unknown; current: { [key: string]: unknown; activeProjects?: number; activityLog?: number; collaboratorsPerProject?: number; commentsPerTask?: number; fileUploadsPerComment?: number; filtersPerUser?: number; labelsPerTask?: number; remindersPerUser?: number; sectionsPerProject?: number; tasksPerProject?: number; }; next: | { [key: string]: unknown; activeProjects?: number; activityLog?: number; collaboratorsPerProject?: number; commentsPerTask?: number; fileUploadsPerComment?: number; filtersPerUser?: number; labelsPerTask?: number; remindersPerUser?: number; sectionsPerProject?: number; tasksPerProject?: number; } | null; }; userSettings?: { [key: string]: unknown; aiEmailAssist: boolean; completedSoundDesktop: boolean; completedSoundMobile: boolean; debugLogSendingEnabledUntil?: string | null; legacyPricing: boolean; navigation: { [key: string]: unknown; countsShown: boolean; features: { name: string; shown: boolean; }[]; }; quickAdd: { [key: string]: unknown; features: { name: string; shown: boolean; }[]; labelsShown: boolean; }; reminderDesktop: boolean; reminderEmail: boolean; reminderPush: boolean; resetRecurringSubtasks: boolean; syncTheme?: boolean; theme?: string | null; }; viewOptions?: { [key: string]: unknown; calendarSettings?: | { [key: string]: unknown; color?: "PROJECT" | "LABEL" | "PRIORITY" | null; layout?: "WEEK" | "MONTH" | null; visibleDayCount?: 3 | 1 | 7 | null; } | null; filteredBy?: string | null; groupedBy?: | "PROJECT" | "LABEL" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | null; isDeleted?: boolean; objectId?: string | null; showCompletedTasks?: boolean; sortedBy?: | "PROJECT" | "ASSIGNEE" | "ADDED_DATE" | "DUE_DATE" | "DEADLINE" | "PRIORITY" | "WORKSPACE" | "MANUAL" | "ALPHABETICALLY" | null; sortOrder?: "ASC" | "DESC" | null; viewMode?: "LIST" | "BOARD" | "CALENDAR" | null; viewType: | "PROJECT" | "TODAY" | "UPCOMING" | "LABEL" | "FILTER" | "WORKSPACE_FILTER" | "SEARCH" | "TEMPLATE_PREVIEW" | "TASK_DETAIL" | "AUTOMATION" | "ASSIGNED" | "OVERDUE" | "WORKSPACE_OVERVIEW"; }[]; workspaceFilters?: { [key: string]: unknown; color: string; createdAt: Date; creatorUid: string; description?: string | null; id: string; isDeleted: boolean; isFavorite: boolean; isFrozen: boolean; itemOrder: number; name: string; query: string; updatedAt: Date; updaterUid: string; workspaceId: string; }[]; workspaces?: { adminSortingApplied: boolean; createdAt: Date | undefined; creatorId: string; currentActiveProjects: number | null; currentMemberCount: number | null; currentTemplateCount: number | null; defaultCollaborators?: { predefinedGroupIds: string[]; userIds: string[]; }; description: string; domainDiscovery?: boolean | null; domainName?: string | null; id: string; inviteCode?: string | null; isCollapsed: boolean; isDeleted: boolean; isGuestAllowed?: boolean | null; isLinkSharingEnabled?: boolean | null; 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; memberCountByType?: { adminCount: number; guestCount: number; memberCount: number; }; name: string; pendingInvitations?: string[] | null; plan: "STARTER" | "BUSINESS"; projectSortPreference?: string | null; properties?: Record<string, unknown>; restrictEmailDomains?: boolean | null; role?: "ADMIN" | "MEMBER" | "GUEST"; }[]; workspaceUsers?: { fullName: string; imageId: string | null; isDeleted: boolean; role: "ADMIN" | "MEMBER" | "GUEST"; timezone: string; userEmail: string; userId: string; workspaceId: string; }[]; }>

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: Date | 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: Date | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: Date | 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: Date | 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: Date;
  archivedAt: Date | null;
  description: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: Date;
  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.

uninstallApp()

uninstallApp(installationId: string, requestId?: string): Promise<boolean>;

Uninstalls (removes) an app installation.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`installationId`	`string`
`requestId?`	`string`

Returns

Promise<boolean>

updateApp()

updateApp(
   appId: string, 
   args: UpdateAppArgs, 
   requestId?: string): Promise<{
  appTokenScopes: string[] | null;
  clientId: string;
  createdAt: Date;
  description: string | null;
  displayName: string;
  iconLg: string | null;
  iconMd: string | null;
  iconSm: string | null;
  id: string;
  oauthRedirectUri: string | null;
  serviceUrl: string | null;
  status: "public";
  userCount: number;
  userId: string;
}>;

Updates a developer application.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`appId`	`string`
`args`	`UpdateAppArgs`
`requestId?`	`string`

Returns

updateAppInstallation()

updateAppInstallation(
   installationId: string, 
   args: UpdateAppInstallationArgs, 
   requestId?: string): Promise<{
  appTokenScopesValidated: boolean;
  createdTs: number;
  creator: string;
  id: string;
  installationType: "user";
  integration:   | {
     appTokenScopes: string[] | null;
     clientId: string;
     createdAt: Date;
     description: string | null;
     displayName: string;
     iconLg: string | null;
     iconMd: string | null;
     iconSm: string | null;
     id: string;
     oauthRedirectUri: string | null;
     serviceUrl: string | null;
     status: "public";
     userId: string;
   }
     | null;
}>;

Updates an app installation.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`installationId`	`string`
`args`	`UpdateAppInstallationArgs`
`requestId?`	`string`

Returns

updateAppWebhook()

updateAppWebhook(args: UpdateAppWebhookArgs, requestId?: string): Promise<{
  callbackUrl: string;
  events: (
     | "project:added"
     | "project:updated"
     | "project:deleted"
     | "project:archived"
     | "project:unarchived"
     | "item:added"
     | "item:updated"
     | "item:completed"
     | "item:uncompleted"
     | "item:deleted"
     | "note:added"
     | "note:updated"
     | "note:deleted"
     | "section:added"
     | "section:updated"
     | "section:deleted"
     | "section:archived"
     | "section:unarchived"
     | "label:added"
     | "label:updated"
     | "label:deleted"
     | "filter:added"
     | "filter:updated"
     | "filter:deleted"
    | "reminder:fired")[];
  status: "active" | "invalid";
  version: "1";
}>;

Creates or updates an app webhook configuration (upsert).

Requires the dev:app_console scope.

Parameters

Parameter	Type
`args`	`UpdateAppWebhookArgs`
`requestId?`	`string`

Returns

Promise<{ callbackUrl: string; events: ( | "project:added" | "project:updated" | "project:deleted" | "project:archived" | "project:unarchived" | "item:added" | "item:updated" | "item:completed" | "item:uncompleted" | "item:deleted" | "note:added" | "note:updated" | "note:deleted" | "section:added" | "section:updated" | "section:deleted" | "section:archived" | "section:unarchived" | "label:added" | "label:updated" | "label:deleted" | "filter:added" | "filter:updated" | "filter:deleted" | "reminder:fired")[]; status: "active" | "invalid"; version: "1"; }>

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: Date;
  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: Date | 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: Date | null;
  url: string;
  viewStyle: string;
}
  | {
  access?: {
     visibility: "restricted" | "team" | "public";
  };
  canAssignTasks: boolean;
  childOrder: number;
  collaboratorRoleDefault: string;
  color: string;
  createdAt: Date | 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: Date | 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: _RequireAtLeastOne, 
   requestId?: string): Promise<{
  addedAt: Date;
  archivedAt: Date | null;
  description: string | null;
  id: string;
  isArchived: boolean;
  isCollapsed: boolean;
  isDeleted: boolean;
  name: string;
  projectId: string;
  sectionOrder: number;
  updatedAt: Date;
  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`	`_RequireAtLeastOne`	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: Date | null;
  addedByUid: string | null;
  assignedByUid: string | null;
  checked: boolean;
  childOrder: number;
  completedAt: Date | 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: Date | 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.

updateUiExtension()

updateUiExtension(
   uiExtensionId: string, 
   args: UpdateUiExtensionArgs, 
   requestId?: string): Promise<
  | {
  contextType: "task" | "project";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "context-menu";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  composerType: "task" | "comment";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "composer";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "settings";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}>;

Updates an existing UI extension.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`uiExtensionId`	`string`
`args`	`UpdateUiExtensionArgs`
`requestId?`	`string`

Returns

updateWorkspace()

updateWorkspace(
   id: string, 
   args: UpdateWorkspaceArgs, 
   requestId?: string): Promise<{
  createdAt: Date | 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.

upgradeToPro()

upgradeToPro(args: UpgradeToProArgs, requestId?: string): Promise<CheckoutSessionResponse>;

Creates a Stripe checkout session to upgrade the current user to Pro.

Requires the billing:read_write scope.

Parameters

Parameter	Type	Description
`args`	`UpgradeToProArgs`	Currency, billing cycle, redirect URLs, and optional promotion/trial details.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<CheckoutSessionResponse>

A promise that resolves to the checkout session URL.

upgradeWorkspace()

upgradeWorkspace(args: UpgradeWorkspaceArgs, requestId?: string): Promise<CheckoutSessionResponse>;

Creates a Stripe checkout session to upgrade a workspace.

Requires the billing:read_write scope.

Parameters

Parameter	Type	Description
`args`	`UpgradeWorkspaceArgs`	Workspace ID, currency, billing cycle, redirect URLs, and optional promotion details.
`requestId?`	`string`	Optional custom identifier for the request.

Returns

Promise<CheckoutSessionResponse>

A promise that resolves to the checkout session URL.

uploadAppIcon()

uploadAppIcon(args: UploadAppIconArgs, requestId?: string): Promise<{
  appTokenScopes: string[] | null;
  clientId: string;
  createdAt: Date;
  description: string | null;
  displayName: string;
  iconLg: string | null;
  iconMd: string | null;
  iconSm: string | null;
  id: string;
  oauthRedirectUri: string | null;
  serviceUrl: string | null;
  status: "public";
  userCount: number;
  userId: string;
}>;

Uploads an icon for a developer application. The size argument selects which icon slot to update (defaults to 'medium').

Requires the dev:app_console scope.

Parameters

Parameter	Type
`args`	`UploadAppIconArgs`
`requestId?`	`string`

Returns

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
  }
})

uploadUiExtensionIcon()

uploadUiExtensionIcon(args: UploadUiExtensionIconArgs, requestId?: string): Promise<
  | {
  contextType: "task" | "project";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "context-menu";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  composerType: "task" | "comment";
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "composer";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}
  | {
  defVersion: number;
  description: string;
  extensionId: string;
  extensionType: "settings";
  height: number | null;
  icon: string | null;
  id: string;
  integrationId: string;
  minimumCardistVersion: string;
  name: string;
  url: string;
  width: number | null;
}>;

Uploads an icon for a UI extension.

Requires the dev:app_console scope.

Parameters

Parameter	Type
`args`	`UploadUiExtensionIconArgs`
`requestId?`	`string`

Returns

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: Date;
  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.).

Only known Todoist attachment hosts are allowed: the authenticated files.todoist.com origin (which receives the Bearer token) and the attachment CDN origins (fetched without the token). Other URLs are rejected.

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`: `Date`; `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, or if the URL is not on a known Todoist attachment host.

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​

addApp()​

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​

addUiExtension()​

Parameters​

Returns​

addWorkspace()​

Parameters​

Returns​

analyzeProjectHealth()​

Parameters​

Returns​

archiveProject()​

Parameters​

Returns​

archiveSection()​

Parameters​

Returns​

cancelPlan()​

Parameters​

Returns​

closeTask()​

Parameters​

Returns​

createAppTestToken()​

Parameters​

Returns​

createProBillingPortalSession()​

Parameters​

Returns​

createProjectFromTemplate()​

Parameters​

Returns​

createWorkspaceBillingPortalSession()​

Parameters​

Returns​

deleteApp()​

Parameters​

Returns​

deleteAppWebhook()​

Parameters​

Returns​

deleteComment()​

Parameters​

Returns​

deleteFolder()​

Parameters​

Returns​

Constructors

Constructor

Parameters

Returns

Methods

acceptWorkspaceInvitation()

Parameters

Returns

addApp()

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

addUiExtension()

Parameters

Returns

addWorkspace()

Parameters

Returns

analyzeProjectHealth()

Parameters

Returns

archiveProject()

Parameters

Returns

archiveSection()

Parameters

Returns

cancelPlan()

Parameters

Returns

closeTask()

Parameters

Returns

createAppTestToken()

Parameters

Returns

createProBillingPortalSession()

Parameters

Returns

createProjectFromTemplate()

Parameters

Returns

createWorkspaceBillingPortalSession()

Parameters

Returns

deleteApp()

Parameters

Returns

deleteAppWebhook()

Parameters

Returns

deleteComment()

Parameters

Returns

deleteFolder()

Parameters

Returns