Author: ThinkR
Date: 2026-02-13

# Complete Guide to rtodoist

#### ThinkR

#### 2026-02-13

# Introduction

The `rtodoist` package provides a comprehensive R interface to the Todoist API v1. This vignette covers all available features including projects, tasks, sections, labels, comments, filters, reminders, and more.

# Getting Started

## Setting Up Your API Token

First, you need to obtain your Todoist API token:

1. Go to Todoist Settings > Integrations > Developer
2. Copy your API token
3. Store it securely in R using keyring

    library(rtodoist)

    # Open the website to find your token
    open_todoist_website_profile()

    # Set your token (only needs to be done once per computer)
    set_todoist_api_token("YOUR_API_TOKEN")

    # Retrieve your stored token
    token <- get_todoist_api_token()

    # Update your token if needed
    update_todoist_api_token()

    # Delete your stored token
    delete_todoist_api_token()

# Projects

## Creating and Managing Projects

    # Create a new project
    project_id <- add_project("My New Project")

    # Get all projects
    projects <- get_all_projects()

    # Get project ID by name
    project_id <- get_project_id("My New Project")

    # Get a single project by ID
    project <- get_project(project_id)

    # Update a project
    update_project(
      project_id = project_id,
      new_name = "Renamed Project",
      color = "blue",
      is_favorite = TRUE,
      view_style = "board"
    )

    # Archive a project
    archive_project(project_id = project_id)

    # Unarchive a project
    unarchive_project(project_id = project_id)

    # Get archived projects
    archived <- get_archived_projects()

    # Delete a project (use with caution!)
    delete_project(project_id = project_id)

# Tasks

## Creating Tasks

    # Add a single task to a project
    project_id %>%
      add_tasks_in_project("My first task")

    # Add multiple tasks
    project_id %>%
      add_tasks_in_project(
        tasks = c("Task 1", "Task 2", "Task 3")
      )

    # Add tasks with due dates and assignees
    project_id %>%
      add_tasks_in_project(
        tasks = c("Task 1", "Task 2"),
        responsible = c("user1@email.com", "user2@email.com"),
        due = c("2024-12-25", "2024-12-31"),
        section_name = c("Section A", "Section B")
      )

    # Add tasks from a data frame
    tasks_df <- data.frame(
      tasks = c("Task A", "Task B", "Task C"),
      responsible = c("user@email.com", "user@email.com", "user@email.com"),
      due = c("2024-12-01", "2024-12-02", "2024-12-03"),
      section_name = c("Section 1", "Section 1", "Section 2")
    )

    add_tasks_in_project_from_df(
      project_id = project_id,
      tasks_as_df = tasks_df
    )

    # Quick add a task using natural language
    quick_add_task("Buy groceries tomorrow at 5pm #Shopping")

## Managing Tasks

    # Get all tasks
    tasks <- get_tasks()

    # Get tasks of a specific project
    project_tasks <- get_tasks_of_project(project_id = project_id)

    # Get a single task by ID
    task <- get_task("task_id")

    # Update a task
    update_task(
      task_id = "task_id",
      content = "Updated task content",
      description = "Task description",
      priority = 4,  # 4 = highest priority
      due_string = "tomorrow",
      labels = c("urgent", "work")
    )

    # Add a responsible person to a task
    add_responsible_to_task(
      project_id = project_id,
      task = "Task 1",
      responsible = "user@email.com"
    )

    # Close (complete) a task
    close_task("task_id")

    # Reopen a task
    reopen_task("task_id")

    # Move a task to another project or section
    move_task(
      task_id = "task_id",
      project_id = "new_project_id",
      section_id = "new_section_id"
    )

    # Delete a task
    delete_task("task_id")

    # Get completed tasks
    completed <- get_completed_tasks(
      project_id = project_id,
      since = "2024-01-01T00:00:00",
      limit = 100
    )

## Filtering Tasks

    # Get tasks by filter query
    today_tasks <- get_tasks_by_filter("today")
    urgent_tasks <- get_tasks_by_filter("p1")
    work_tasks <- get_tasks_by_filter("#Work")
    overdue_tasks <- get_tasks_by_filter("overdue")
    combined_filter <- get_tasks_by_filter("today & p1 & #Work")

# Sections

## Managing Sections

    # Create a section
    section_id <- add_section(
      section_name = "New Section",
      project_id = project_id
    )

    # Get all sections
    all_sections <- get_all_sections()

    # Get sections from a specific project
    project_sections <- get_section_from_project(project_id = project_id)

    # Get section ID by name
    section_id <- get_section_id(
      project_id = project_id,
      section_name = "New Section"
    )

    # Get a single section by ID
    section <- get_section("section_id")

    # Update a section
    update_section(
      section_id = section_id,
      new_name = "Renamed Section"
    )

    # Move a section to another project
    move_section(
      section_id = section_id,
      project_id = "target_project_id"
    )

    # Archive a section
    archive_section(section_id = section_id)

    # Unarchive a section
    unarchive_section(section_id = section_id)

    # Delete a section
    delete_section(section_id = section_id)

# Labels

## Managing Labels

    # Create a label
    label_id <- add_label(
      name = "urgent",
      color = "red",
      is_favorite = TRUE
    )

    # Get all labels
    labels <- get_all_labels()

    # Get a single label by ID
    label <- get_label("label_id")

    # Get label ID by name
    label_id <- get_label_id("urgent")

    # Update a label
    update_label(
      label_id = label_id,
      new_name = "very_urgent",
      color = "orange"
    )

    # Delete a label
    delete_label(label_id = label_id)

    # Get shared labels (in workspaces)
    shared_labels <- get_shared_labels()

    # Rename a shared label
    rename_shared_label("old_name", "new_name")

    # Remove a shared label
    remove_shared_label("label_name")

# Comments

## Managing Comments

    # Add a comment to a task
    comment_id <- add_comment(
      content = "This is a comment",
      task_id = "task_id"
    )

    # Add a comment to a project
    comment_id <- add_comment(
      content = "Project-level comment",
      project_id = project_id
    )

    # Get comments on a task
    task_comments <- get_comments(task_id = "task_id")

    # Get comments on a project
    project_comments <- get_comments(project_id = project_id)

    # Get a single comment by ID
    comment <- get_comment("comment_id")

    # Update a comment
    update_comment(
      comment_id = "comment_id",
      content = "Updated comment content"
    )

    # Delete a comment
    delete_comment("comment_id")

# Filters

## Managing Custom Filters

    # Create a filter
    filter_id <- add_filter(
      name = "Urgent Today",
      query = "today & p1",
      color = "red",
      is_favorite = TRUE
    )

    # Get all filters
    filters <- get_all_filters()

    # Get a single filter by ID
    filter <- get_filter("filter_id")

    # Get filter ID by name
    filter_id <- get_filter_id("Urgent Today")

    # Update a filter
    update_filter(
      filter_id = filter_id,
      query = "today & (p1 | p2)",
      new_name = "Urgent & Important Today"
    )

    # Delete a filter
    delete_filter(filter_id = filter_id)

# Reminders

## Managing Reminders

    # Add an absolute reminder
    reminder_id <- add_reminder(
      task_id = "task_id",
      due_datetime = "2024-12-25T09:00:00",
      type = "absolute"
    )

    # Add a relative reminder (30 minutes before)
    reminder_id <- add_reminder(
      task_id = "task_id",
      minute_offset = 30,
      type = "relative"
    )

    # Get all reminders
    reminders <- get_all_reminders()

    # Update a reminder
    update_reminder(
      reminder_id = reminder_id,
      due_datetime = "2024-12-25T10:00:00"
    )

    # Delete a reminder
    delete_reminder(reminder_id)

# Collaboration

## Managing Users and Collaborators

    # Get all collaborators
    users <- get_all_users()

    # Get user IDs by email
    user_ids <- get_users_id(mails = c("user1@email.com", "user2@email.com"))

    # Add a single user to a project
    add_user_in_project(
      project_id = project_id,
      mail = "user@email.com"
    )

    # Add multiple users to a project
    add_users_in_project(
      project_id = project_id,
      users_email = c("user1@email.com", "user2@email.com")
    )

    # Get users in a project
    project_users <- get_users_in_project(project_id = project_id)

    # Remove a collaborator from a project
    delete_collaborator(
      project_id = project_id,
      email = "user@email.com"
    )

## User Information

    # Get current user info
    user_info <- get_user_info()

    # Get productivity stats
    stats <- get_productivity_stats()

## Invitations

    # Accept an invitation
    accept_invitation(
      invitation_id = "invitation_id",
      invitation_secret = "secret"
    )

    # Reject an invitation
    reject_invitation(
      invitation_id = "invitation_id",
      invitation_secret = "secret"
    )

    # Delete an invitation
    delete_invitation("invitation_id")

# Workspaces

## Managing Workspaces

    # Get all workspaces
    workspaces <- get_all_workspaces()

    # Get workspace users
    workspace_users <- get_workspace_users()

    # Invite user to workspace
    invite_to_workspace(
      workspace_id = "workspace_id",
      email = "user@email.com",
      role = "member"
    )

    # Update workspace
    update_workspace(
      workspace_id = "workspace_id",
      name = "New Workspace Name"
    )

    # Leave a workspace
    leave_workspace("workspace_id")

# Activity Logs

    # Get activity logs
    activity <- get_activity_logs(
      object_type = "item",
      event_type = "completed",
      limit = 50
    )

# Templates

## Import and Export Templates

    # Export a project as a template
    export_template(
      project_id = project_id,
      output_file = "my_template.csv"
    )

    # Import a template into a project
    import_template(
      project_id = project_id,
      file_path = "my_template.csv"
    )

# Backups

## Managing Backups

    # Get list of available backups
    backups <- get_backups()

    # Download a backup
    download_backup(
      version = backups$version[1],
      output_file = "todoist_backup.zip"
    )

# File Uploads

## Managing File Attachments

    # Upload a file
    upload_result <- upload_file("document.pdf")

    # The upload result contains a file_url that can be used in comments
    add_comment(
      content = paste("Attached file:", upload_result$file_url),
      task_id = "task_id"
    )

    # Delete an uploaded file
    delete_upload(file_url = upload_result$file_url)

# Complete Workflow Example

Here’s a complete example showing a typical workflow:

    library(rtodoist)
    library(lubridate)

    # Create a new project
    project_id <- add_project("Q1 2024 Goals")

    # Add sections
    add_section("Personal", project_id = project_id)
    add_section("Work", project_id = project_id)
    add_section("Health", project_id = project_id)

    # Create labels
    add_label("high-priority", color = "red")
    add_label("quick-win", color = "green")

    # Add tasks with sections and due dates
    project_id %>%
      add_tasks_in_project(
        tasks = c(
          "Complete project proposal",
          "Review team performance",
          "Plan Q2 roadmap"
        ),
        due = c(
          as.character(today() + days(7)),
          as.character(today() + days(14)),
          as.character(today() + months(1))
        ),
        section_name = c("Work", "Work", "Work")
      )

    project_id %>%
      add_tasks_in_project(
        tasks = c(
          "Run 5K",
          "Meal prep Sunday",
          "Schedule annual checkup"
        ),
        section_name = c("Health", "Health", "Health")
      )

    # Create a filter for important work tasks
    add_filter(
      name = "Important Work",
      query = "#Work & (p1 | p2)",
      is_favorite = TRUE
    )

    # Add a reminder for the first task
    tasks <- get_tasks_of_project(project_id = project_id)
    first_task_id <- tasks[[1]]$id

    add_reminder(
      task_id = first_task_id,
      due_datetime = paste0(today() + days(6), "T09:00:00"),
      type = "absolute"
    )

    # Export as template for future use
    export_template(
      project_id = project_id,
      output_file = "quarterly_goals_template.csv"
    )

    # View today's tasks
    today_tasks <- get_tasks_by_filter("today")
    print(today_tasks)

# API Reference

For more details on the Todoist API, see:

- Todoist API Documentation

# Session Info

    sessionInfo()
    #> R version 4.5.0 (2025-04-11 ucrt)
    #> Platform: x86_64-w64-mingw32/x64
    #> Running under: Windows 11 x64 (build 26100)
    #>
    #> Matrix products: default
    #>   LAPACK version 3.12.1
    #>
    #> locale:
    #> [1] LC_COLLATE=C                   LC_CTYPE=French_France.utf8
    #> [3] LC_MONETARY=French_France.utf8 LC_NUMERIC=C
    #> [5] LC_TIME=French_France.utf8
    #>
    #> time zone: Europe/Paris
    #> tzcode source: internal
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] digest_0.6.39     R6_2.6.1          fastmap_1.2.0     xfun_0.55
    #>  [5] cachem_1.1.0      knitr_1.51        htmltools_0.5.8.1 rmarkdown_2.30
    #>  [9] lifecycle_1.0.5   cli_3.6.5         sass_0.4.10       jquerylib_0.1.4
    #> [13] compiler_4.5.0    rstudioapi_0.18.0 tools_4.5.0       evaluate_1.0.5
    #> [17] bslib_0.9.0       yaml_2.3.10       otel_0.2.0        jsonlite_1.8.8
    #> [21] rlang_1.1.7