Introduction

This a library is a Nim client for the Todoist REST API.

Authentication

To initialize a Todoist client you must instantiate it with your personal tokek

import todoist

let client = Todoist("abcd123...")

To use todoist you need an authorization key. This can be requested from the Todoist app management.

Once the client has been initialized, all the subsequent oprations can be requested from your client instance.

Projects

Structure

This will return a seq[TodoistProject] where TodoistProject is

type TodoistProject* = object
    id*: int
    order*: Option[int] 
    color*: int
    name*: string
    comment_count*: int
    `shared`*: bool
    favorite*: bool
    sync_id*: int
    url*: string

A project is represented by a TodoistProject object. The available fields are:

• id, project ID
• order, project position under the same parent (read-only)
• color, a numeric ID representing the color of the project icon
• name, project name
• comment_count, number of project comments
• shared, whether the project is shared
• favorite, whether the project is a favorite
• sync_id, identifier to find the match between different copies of shared projects
• url, URL to access this project in the Todoist web or mobile applications

Get all projects

import todoist

let client = Todoist("abcd123...")

let projects = client.getAllProject()

To get all the projects use client.getAllProjects(). The result is a seq[TodoistProject] containing all the projects or an empty seq if none.

Get a specific project

let id = 1234 # ... project id
client.getProject(id)

Getting a specific project with id

To retrieve a specific project, call client.getProject(id), where id is the project id.

Tasks

Structure

The structure of a TodoistTask is

type TodoistTask* = object
    id*: int
    project_id*: int
    section_id*: int
    parent_id*: Option[int]
    order*: int
    content*: string
    description*: string
    completed*: bool
    label_ids*: seq[int]
    priority*: int
    comment_count*: int
    created*: string
    due*: Option[DueDate]

Tasks are represented by TodoistTask. The fields are:

• id, the task ID
• project_id, the task's project ID (read-only)
• section_id, ID of section task belongs to
• parent_id, ID of parent task (read-only, absent for top-level tasks)
• order, position under the same parent or project for top-level tasks (read-only)
• content, task content. This value may contain markdown-formatted text and hyperlinks
• description, a description for the task. This value may contain markdown-formatted text and hyperlinks
• completed, flag to mark completed tasks
• label_ids, array of label IDs, associated with a task
• priority, task priority from 1 (normal, default value) to 4 (urgent)
• comment_count, number of task comments
• due, object representing task due date/time (see below)

Due date

The structure of a DueDate is

type DueDate* = object
    recurring*: bool
    `string`*: string
    date*: string

Get all active tasks

import todoist

let client = Todoist("abcd123...")

let tasks = client.getActiveTasks()

To get all active tasks use client.getActiveTasks(). The result is a seq[TodoistTask] containing all the active tasks or an empty seq if none.

Get a specific tasks

let task_id = 1234 # ... task id
client.getTask(task_id)

Getting a specific task with task_id

To retrieve a specific task, call client.getTask(task_id), where task_id is the task id.

Sections

Structure

The structure of a TodoistSection is

type TodoistSection* = object
    id*: int
    project_id*: int
    order*: int
    name*: string

Sections are represented by TodoistSection. The fields are:

• id, section id
• project_id, ID of the project section belongs to
• order, section position among other sections from the same project
• name, section name

Get project's sections

import todoist

let client = Todoist("abcd123...")
let project_id = 1234
let sections = client.getProjectSections(project_id)

To get a project's sections use client.getProjectSections(). The result is a seq[TodoistSection] containing all the sections or an empty seq if none.

Labels

Structure

The structure of a TodoistLabel is

type TodoistLabel* = object
    id*:int # Label ID
    name*:string # Label name
    color*:int # A numeric ID representing the color of the label icon
    order*: int # Number used by clients to sort list of labels
    favorite*: bool # Whether the label is a favorite

Labels are represented by TodoistLabel. The fields are:

• id, label ID
• name, label name
• color, a numeric ID representing the color of the label icon
• order, number used by clients to sort list of labels
• favorite, whether the label is a favorite

Get all labels

import todoist

let client = Todoist("abcd123...")
let labels = client.getAllLabels()

To get all labels use client.getAllLabels(). The result is a seq[TodoistLabel] containing all the labels or an empty seq if none.