Class Todoist

Update Note Drafts v49 modified convenience methods on this object to point to the new v1 API. Previous REST API is being shutdown in February 2026.

Script integration with Todoist. This object handles OAuth authentication and request signing. The entire Todoist API can be used with the request method, and convenience methods are provided for common API endpoints to manage tasks, projects, comments and labels.

The quickAdd method is mostly likely what you are looking for to create tasks as it supports the shorthand the task entry box in Todoist supports to parse projects, etc.

Other methods are direct mappings of the API calls provided by Todoist. Most take an options parameter which is a javascript object containing the parameters to be passed to the API, and and the method decodes the JSON response from Todoist and returns it as a Javascript object (or array of objects) with the values as specified in the Todoist API docs.

Note that the get... methods that return multiple items will return the array of items from the Todoist response, not the entire response object. This is to maintain compatibility with older versions of the API. If you need support for pagination, you can use the request method to make direct API calls, or access the full response in the lastResponse property after making one of these calls.

If an API calls fails, typically the result will be an undefined value, and the lastError property will contains error detail information for troubleshooting.

Example

See Examples-Todoist action group in the Action Directory.

// create Todoist object
let todoist = Todoist.create();
// create task in inbox
todoist.createTask({
  "content": "My Task Name",
  "due_string": "Next wednesday"
});

Index

Comments

createComment

createComment(options: object): object
Create new comment. API reference
Parameters
- options: object
Returns object

getComment

getComment(commentId: string): object
Get comment. API reference
Parameters
- commentId: string
Returns object

getComments

getComments(options: object): object[]
Get comments. If you need access to the full response for pagination, it can be accessed using the lastResponse property after the method call. API reference
Parameters
- options: object
Returns object[]

updateComment

updateComment(commentId: string, options: object): object
Update comment. API reference
Parameters
- commentId: string
- options: object
Returns object

Labels

createLabel

createLabel(options: object): object
Create new labels. API reference
Parameters
- options: object
Returns object

getLabel

getLabel(labelId: string): object
Get label. API reference
Parameters
- labelId: string
Returns object

getLabels

getLabels(options?: object): object[]
Get labels. If you need access to the full response for pagination, it can be accessed using the lastResponse property after the method call. API reference
Parameters
- Optionaloptions: object
Returns object[]

updateLabel

updateLabel(labelId: string, options: object): object
Update label. API reference
Parameters
- labelId: string
- options: object
Returns object

Other

constructor

new Todoist(identifier?: string): Todoist
Create new instance.
Parameters
- Optionalidentifier: string
Returns Todoist

`Optional`lastError

lastError?: string

If a function fails, this property will contain the last error as a string message, otherwise it will be undefined.

lastResponse

lastResponse: any

If a function succeeds, this property will contain the last response returned by Todoist. The JSON returned by Todoist will be parsed to an object and placed in this property. Refer to API reference for details on the contents of this object based on call made.

quickAdd

quickAdd(
    text: string,
    note?: string,
    reminder?: string,
    options?: object,
): object
Parameters
- text: string
  Text to use to create the task. Supports Todoist quick add notation for specifying projects, priority, labels, etc. just as if you were using the Todoist quick add window.
- Optionalnote: string
  Optional text to attach as a comment with the task.
- Optionalreminder: string
  Optional natural language date specifying for creating a task reminder.
- Optionaloptions: object
  Optional dictionary of additional parameters to include in the request.
Returns object
Object containing respose data from Todoist.

request

request(
    settings: {
        data?: { [x: string]: string };
        headers?: { [x: string]: string };
        method: string;
        parameters?: { [x: string]: string };
        url: string;
    },
): HTTPResponse
Execute a request against the Todoist API. For successful requests, the HTTPResponse object will contain an object or array or objects decoded from the JSON returned by Todoist as appropriate to the request made. Refer to Todoist’s API documentation for details about the expected parameters and responses. Drafts will handle wrapping the request in the appropriate OAuth authentication flow.
Parameters
- settings: {
      data?: { [x: string]: string };
      headers?: { [x: string]: string };
      method: string;
      parameters?: { [x: string]: string };
      url: string;
  }
  an object configuring the request.
  - Optionaldata?: { [x: string]: string }
    A JavaScript object containing data to be encoded into the HTTP body of the request.
  - Optionalheaders?: { [x: string]: string }
    An object contain key-values to be added as custom headers in the request. There is no need to provide authorization headers, Drafts will add those.
  - method: string
    The HTTP method, like "GET", "POST", etc.
  - Optionalparameters?: { [x: string]: string }
    An object containing key-values to be added to the request as URL parameters.
  - url: string
    The full URL to the endpoint in the Todoist REST API.
Returns HTTPResponse

`Static`create

create(identifier: string): Todoist
Creates a new Todoist object.
Parameters
- identifier: string
  Optional string value used to identify a Todoist account. Typically this can be omitted if you only work with one Todoist account in Drafts. Each unique identifier used for Todoist accounts will share credentials - across both action steps and scripts.
Returns Todoist

Projects

createProject

createProject(options: object): object
Create new project. API reference
Parameters
- options: object
Returns object

getProject

getProject(projectId: string): object
Get project. API reference
Parameters
- projectId: string
Returns object

getProjects

getProjects(options?: object): object[]
Get all projects. Returns the result key from the response, which is an array of objects. If you need access to the full response for pagination, it can be accessed using the lastResponse property after the method call. API reference
Parameters
- Optionaloptions: object
Returns object[]

updateProject

updateProject(projectId: string, options: object): object
Update project. API reference
Parameters
- projectId: string
- options: object
Returns object

Sections

createSection

createSection(options: object): object
Create new section. API reference
Parameters
- options: object
Returns object

getProjectSections

getProjectSections(projectId: string): object[]
Get project sections. If you need access to the full response for pagination, it can be accessed using the lastResponse property after the method call. API reference
Parameters
- projectId: string
Returns object[]

getSection

getSection(sectionId: string): object
Get section. API reference
Parameters
- sectionId: string
Returns object

getSections

getSections(options?: object): object[]
Get sections. If you need access to the full response for pagination, it can be accessed using the lastResponse property after the method call. API reference
Parameters
- Optionaloptions: object
Returns object[]

updateSection

updateSection(sectionId: string, options: object): object
Update section. API reference
Parameters
- sectionId: string
- options: object
Returns object

Tasks

closeTask

closeTask(taskId: string): boolean
Close task (mark complete). API reference
Parameters
- taskId: string
Returns boolean

createTask

createTask(options: object): object
Create new task. API reference
Parameters
- options: object
  Optional dictionary of additional parameters to include in the request.
Returns object

getTask

getTask(taskId: string): object
Get task. API reference
Parameters
- taskId: string
Returns object

getTasks

getTasks(options?: object): object[]
Get active tasks. API reference
Parameters
- Optionaloptions: object
  Optional dictionary of additional parameters to include in the request.
Returns object[]

getTasksByFilter

getTasksByFilter(options?: object): object[]
Get tasks that match the filter parameter passed. API reference
Parameters
- Optionaloptions: object
  Optional dictionary of additional parameters to include in the request.
Returns object[]

reopenTask

reopenTask(taskId: string): boolean
Reopen task (mark incomplete). API reference
Parameters
- taskId: string
Returns boolean

updateTask

updateTask(taskId: string, options: object): object
Update active task. API reference
Parameters
- taskId: string
- options: object
Returns object

Class Todoist

Example

Index

Comments

Labels

Other

Projects

Sections

Tasks

Comments

createComment

Parameters

Returns object

getComment

Parameters

Returns object

getComments

Parameters

Returns object[]

updateComment

Parameters

Returns object

Labels

createLabel

Parameters

Returns object

getLabel

Parameters

Returns object

getLabels

Parameters

Returns object[]

updateLabel

Parameters

Returns object

Other

constructor

Parameters

Returns Todoist

OptionallastError

lastResponse

quickAdd

Parameters

Returns object

request

Parameters

Optionaldata?: { [x: string]: string }

Optionalheaders?: { [x: string]: string }

method: string

Optionalparameters?: { [x: string]: string }

url: string

Returns HTTPResponse

Staticcreate

Parameters

Returns Todoist

Projects

createProject

Parameters

Returns object

getProject

Parameters

Returns object

getProjects

Parameters

Returns object[]

updateProject

Parameters

Returns object

Sections

createSection

Parameters

Returns object

getProjectSections

Parameters

Returns object[]

getSection

Parameters

Returns object

getSections

Parameters

`Optional`lastError

`Optional`data?: { [x: string]: string }

`Optional`headers?: { [x: string]: string }

`Optional`parameters?: { [x: string]: string }

`Static`create