todoist

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 24, 2026 License: MIT Imports: 14 Imported by: 0

README

go-todoist

A clean, idiomatic Go client for the Todoist API v1 — the unified API that merges the former REST and Sync APIs.

  • Zero external dependencies (standard library only).
  • context.Context on every call.
  • Cursor pagination exposed both as raw pages and as iter.Seq2 iterators.
  • REST coverage for tasks, projects, sections, labels, comments, reminders, workspaces, and user, plus the batched Sync API. (Filters have no REST endpoint in v1 and are managed via Sync.)

Requires Go 1.23+ (uses range-over-function iterators).

Install

go get github.com/smirnoffmg/go-todoist

Authentication

Create a client with a personal API token (Todoist → Settings → Integrations → Developer) or an OAuth2 access token:

api := todoist.New(os.Getenv("TODOIST_TOKEN"))

Options: WithHTTPClient, WithBaseURL, WithUserAgent.

Tasks and pagination

Each list resource has two forms: a low-level page fetch (GetTasks) and an auto-paginating iterator (Tasks) that transparently follows the cursor.

ctx := context.Background()
api := todoist.New(os.Getenv("TODOIST_TOKEN"))

// Iterate over every task, following pagination automatically.
for task, err := range api.Tasks(ctx, &todoist.GetTasksArgs{ProjectID: "220474322"}) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(task.ID, task.Content)
}

// Or fetch a single page and manage the cursor yourself.
page, err := api.GetTasks(ctx, &todoist.GetTasksArgs{Limit: 50})
if err != nil {
    log.Fatal(err)
}
fmt.Println(len(page.Results), page.NextCursor)

Create, update, and complete a task:

task, err := api.CreateTask(ctx, todoist.CreateTaskArgs{
    Content:   "Buy milk",
    DueString: todoist.Ptr("tomorrow at 9am"),
    Priority:  todoist.Ptr(todoist.PriorityHigh),
})
if err != nil {
    log.Fatal(err)
}

_, _ = api.UpdateTask(ctx, task.ID, todoist.UpdateTaskArgs{Content: todoist.Ptr("Buy oat milk")})
_ = api.CloseTask(ctx, task.ID)

Optional request fields are pointers so an unset field is omitted rather than sent as a zero value. Use the Ptr helper to set them inline.

Error handling

Non-2xx responses return an *todoist.Error carrying the status and body. On rate limiting (429) it also exposes RetryAfter.

_, err := api.GetTask(ctx, "bad-id")
var apiErr *todoist.Error
if errors.As(err, &apiErr) {
    fmt.Println(apiErr.StatusCode, apiErr.RetryAfter)
    if apiErr.Temporary() {
        // safe to retry after apiErr.RetryAfter
    }
}

Sync API

The Sync endpoint batches multiple write commands in one round trip and supports incremental sync via a persisted token. Commands can reference each other's temp_id.

addProject := todoist.NewCommand("project_add", "proj-tmp", map[string]any{"name": "Launch"})
addTask := todoist.NewCommand("item_add", "", map[string]any{
    "content":    "Draft announcement",
    "project_id": "proj-tmp", // resolved via temp_id mapping
})

resp, err := api.Sync(ctx, todoist.SyncRequest{
    ResourceTypes: []string{"projects", "items"},
    Commands:      []todoist.Command{addProject, addTask},
})
if err != nil {
    log.Fatal(err)
}
if err := resp.Err(); err != nil {
    log.Fatal(err) // aggregates per-command failures
}

realProjectID := resp.TempIDMapping["proj-tmp"]
fmt.Println("created project", realProjectID)

// Persist resp.SyncToken and pass it back next time for an incremental sync.

Development

make lint   # golangci-lint run
make test   # go test -race -cover ./... (offline; 100% coverage)
Testing against real Todoist

Integration tests hit the live API. They are gated behind the integration build tag so they never run in the normal offline suite or CI, and they skip automatically unless TODOIST_TOKEN is set. Each test creates its own scratch project/label and deletes it on cleanup, so your existing data is left untouched.

Get a personal token from Todoist → Settings → Integrations → Developer, then:

export TODOIST_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
make test-integration
# or:
go test -tags=integration -run Integration -v ./...

These tests cover the full round trip: authenticating (GetUser), the task lifecycle (create → get → update → close → reopen → delete), sections and comments, labels, project pagination via the iterator, and a read-only Sync.

License

See LICENSE.

Documentation

Overview

Package todoist is a client for the unified Todoist API v1 (https://developer.todoist.com/api/v1/).

It has no external dependencies, takes a context.Context on every call, and exposes cursor pagination both as raw pages and as range-over-function iterators.

Authentication

Construct a client with a personal or OAuth2 token: 

api := todoist.New(os.Getenv("TODOIST_TOKEN"))

Pagination

List endpoints have two forms: a low-level page fetch (for example GetTasks) returning a Page, and an auto-paginating iterator (for example Tasks) returning an iter.Seq2 that transparently follows the cursor: 

for task, err := range api.Tasks(ctx, nil) {
    if err != nil {
        return err
    }
    fmt.Println(task.Content)
}

Errors

Non-2xx responses are returned as *Error, which carries the status, body, and (on HTTP 429) a RetryAfter duration.

Filters

Todoist API v1 has no REST endpoints for filters; they are managed through the Sync API. See Client.Sync and NewCommand.

Index

Examples

Constants

View Source 
const (
	PriorityNormal = 1
	PriorityMedium = 2
	PriorityHigh   = 3
	PriorityUrgent = 4
)

Priority levels for tasks. The API uses 1 (natural, lowest) through 4 (urgent, highest); note this is the reverse of what the Todoist UI shows.

View Source 
const DefaultBaseURL = "https://api.todoist.com/api/v1"

DefaultBaseURL is the root of the Todoist API v1.

Variables

This section is empty.

Functions

func NewUUID 

func NewUUID() string

NewUUID returns a random RFC 4122 version 4 UUID string, suitable for command and temp IDs.

func Ptr 

func Ptr[T any](v T) *T

Ptr returns a pointer to v. It is a convenience for setting the optional pointer fields on request argument structs inline.

Types

type Attachment 

type Attachment struct {
	ResourceType string `json:"resource_type,omitempty"`
	FileName     string `json:"file_name,omitempty"`
	FileType     string `json:"file_type,omitempty"`
	FileURL      string `json:"file_url,omitempty"`
	FileSize     int    `json:"file_size,omitempty"`
	UploadState  string `json:"upload_state,omitempty"`
}

Attachment describes a file attached to a comment.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a Todoist API v1 client. It is safe for concurrent use as long as its configuration is not mutated after construction.

func New 

func New(token string, opts ...Option) *Client

New returns a Client authenticated with the given personal or OAuth2 token.

Example 
package main

import (
	"os"

	todoist "github.com/smirnoffmg/go-todoist"
)

func main() {
	api := todoist.New(os.Getenv("TODOIST_TOKEN"))
	_ = api
}

func (*Client) ArchiveProject 

func (c *Client) ArchiveProject(ctx context.Context, id string) error

ArchiveProject archives a project.

func (*Client) CloseTask 

func (c *Client) CloseTask(ctx context.Context, id string) error

CloseTask marks a task as complete.

func (*Client) Comments 

func (c *Client) Comments(ctx context.Context, args *GetCommentsArgs) iter.Seq2[Comment, error]

Comments returns an iterator over all comments matching args, following pagination.

func (*Client) CreateComment 

func (c *Client) CreateComment(ctx context.Context, args CreateCommentArgs) (Comment, error)

CreateComment creates a new comment.

func (*Client) CreateLabel 

func (c *Client) CreateLabel(ctx context.Context, args CreateLabelArgs) (Label, error)

CreateLabel creates a new personal label.

func (*Client) CreateProject 

func (c *Client) CreateProject(ctx context.Context, args CreateProjectArgs) (Project, error)

CreateProject creates a new project.

func (*Client) CreateReminder 

func (c *Client) CreateReminder(ctx context.Context, args CreateReminderArgs) (Reminder, error)

CreateReminder creates a new reminder.

func (*Client) CreateSection 

func (c *Client) CreateSection(ctx context.Context, args CreateSectionArgs) (Section, error)

CreateSection creates a new section.

func (*Client) CreateTask 

func (c *Client) CreateTask(ctx context.Context, args CreateTaskArgs) (Task, error)

CreateTask creates a new task.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	todoist "github.com/smirnoffmg/go-todoist"
)

func main() {
	api := todoist.New(os.Getenv("TODOIST_TOKEN"))

	task, err := api.CreateTask(context.Background(), todoist.CreateTaskArgs{
		Content:   "Buy milk",
		DueString: todoist.Ptr("tomorrow at 9am"),
		Priority:  todoist.Ptr(todoist.PriorityHigh),
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(task.ID)
}

func (*Client) CreateWorkspace 

func (c *Client) CreateWorkspace(ctx context.Context, args CreateWorkspaceArgs) (Workspace, error)

CreateWorkspace creates a new workspace.

func (*Client) DeleteComment 

func (c *Client) DeleteComment(ctx context.Context, id string) error

DeleteComment deletes a comment.

func (*Client) DeleteLabel 

func (c *Client) DeleteLabel(ctx context.Context, id string) error

DeleteLabel deletes a label.

func (*Client) DeleteProject 

func (c *Client) DeleteProject(ctx context.Context, id string) error

DeleteProject deletes a project.

func (*Client) DeleteReminder 

func (c *Client) DeleteReminder(ctx context.Context, id string) error

DeleteReminder deletes a reminder.

func (*Client) DeleteSection 

func (c *Client) DeleteSection(ctx context.Context, id string) error

DeleteSection deletes a section and all of its tasks.

func (*Client) DeleteTask 

func (c *Client) DeleteTask(ctx context.Context, id string) error

DeleteTask deletes a task.

func (*Client) GetCollaborators 

func (c *Client) GetCollaborators(ctx context.Context, projectID string, args *GetProjectsArgs) (Page[Collaborator], error)

GetCollaborators returns a page of collaborators for a shared project.

func (*Client) GetComment 

func (c *Client) GetComment(ctx context.Context, id string) (Comment, error)

GetComment returns a single comment by ID.

func (*Client) GetComments 

func (c *Client) GetComments(ctx context.Context, args *GetCommentsArgs) (Page[Comment], error)

GetComments returns a single page of comments.

func (*Client) GetLabel 

func (c *Client) GetLabel(ctx context.Context, id string) (Label, error)

GetLabel returns a single label by ID.

func (*Client) GetLabels 

func (c *Client) GetLabels(ctx context.Context, args *GetLabelsArgs) (Page[Label], error)

GetLabels returns a single page of labels.

func (*Client) GetProductivityStats 

func (c *Client) GetProductivityStats(ctx context.Context) (ProductivityStats, error)

GetProductivityStats returns the authenticated user's completed-task and karma statistics.

func (*Client) GetProject 

func (c *Client) GetProject(ctx context.Context, id string) (Project, error)

GetProject returns a single project by ID.

func (*Client) GetProjects 

func (c *Client) GetProjects(ctx context.Context, args *GetProjectsArgs) (Page[Project], error)

GetProjects returns a single page of projects.

func (*Client) GetReminders 

func (c *Client) GetReminders(ctx context.Context, args *GetRemindersArgs) (Page[Reminder], error)

GetReminders returns a single page of reminders.

func (*Client) GetSection 

func (c *Client) GetSection(ctx context.Context, id string) (Section, error)

GetSection returns a single section by ID.

func (*Client) GetSections 

func (c *Client) GetSections(ctx context.Context, args *GetSectionsArgs) (Page[Section], error)

GetSections returns a single page of sections.

func (*Client) GetTask 

func (c *Client) GetTask(ctx context.Context, id string) (Task, error)

GetTask returns a single task by ID.

func (*Client) GetTasks 

func (c *Client) GetTasks(ctx context.Context, args *GetTasksArgs) (Page[Task], error)

GetTasks returns a single page of tasks matching args.

func (*Client) GetUser 

func (c *Client) GetUser(ctx context.Context) (User, error)

GetUser returns the authenticated user's profile.

func (*Client) GetWorkspace 

func (c *Client) GetWorkspace(ctx context.Context, id string) (Workspace, error)

GetWorkspace returns a single workspace by ID.

func (*Client) GetWorkspaceUsers 

func (c *Client) GetWorkspaceUsers(ctx context.Context, args *GetWorkspaceUsersArgs) (Page[WorkspaceUser], error)

GetWorkspaceUsers returns a page of members of a workspace.

func (*Client) GetWorkspaces 

func (c *Client) GetWorkspaces(ctx context.Context) ([]Workspace, error)

GetWorkspaces returns the workspaces the user belongs to. Unlike the other list endpoints this one is not paginated and returns a plain array.

func (*Client) Labels 

func (c *Client) Labels(ctx context.Context, args *GetLabelsArgs) iter.Seq2[Label, error]

Labels returns an iterator over all labels, following pagination.

func (*Client) Projects 

func (c *Client) Projects(ctx context.Context, args *GetProjectsArgs) iter.Seq2[Project, error]

Projects returns an iterator over all projects, following pagination.

func (*Client) QuickAddTask 

func (c *Client) QuickAddTask(ctx context.Context, text string) (Task, error)

QuickAddTask creates a task using Todoist's natural-language quick-add syntax.

func (*Client) Reminders 

func (c *Client) Reminders(ctx context.Context, args *GetRemindersArgs) iter.Seq2[Reminder, error]

Reminders returns an iterator over all reminders, following pagination.

func (*Client) ReopenTask 

func (c *Client) ReopenTask(ctx context.Context, id string) error

ReopenTask reopens a previously completed task.

func (*Client) Sections 

func (c *Client) Sections(ctx context.Context, args *GetSectionsArgs) iter.Seq2[Section, error]

Sections returns an iterator over all sections, following pagination.

func (*Client) Sync 

func (c *Client) Sync(ctx context.Context, req SyncRequest) (*SyncResponse, error)

Sync performs a synchronization request against the /sync endpoint, batching any commands in req. Callers should persist the returned SyncToken to make subsequent incremental syncs.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	todoist "github.com/smirnoffmg/go-todoist"
)

func main() {
	api := todoist.New(os.Getenv("TODOIST_TOKEN"))

	addProject := todoist.NewCommand("project_add", "proj-tmp", map[string]any{"name": "Launch"})
	addTask := todoist.NewCommand("item_add", "", map[string]any{
		"content":    "Draft announcement",
		"project_id": "proj-tmp", // resolved via temp_id mapping
	})

	resp, err := api.Sync(context.Background(), todoist.SyncRequest{
		ResourceTypes: []string{"projects", "items"},
		Commands:      []todoist.Command{addProject, addTask},
	})
	if err != nil {
		log.Fatal(err)
	}
	if err := resp.Err(); err != nil {
		log.Fatal(err)
	}
	fmt.Println("created project", resp.TempIDMapping["proj-tmp"])
	// Persist resp.SyncToken for the next incremental sync.
}

func (*Client) Tasks 

func (c *Client) Tasks(ctx context.Context, args *GetTasksArgs) iter.Seq2[Task, error]

Tasks returns an iterator over all tasks matching args, transparently following pagination cursors.

Example 
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	todoist "github.com/smirnoffmg/go-todoist"
)

func main() {
	api := todoist.New(os.Getenv("TODOIST_TOKEN"))

	// The iterator follows pagination cursors automatically.
	for task, err := range api.Tasks(context.Background(), &todoist.GetTasksArgs{ProjectID: "220474322"}) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(task.ID, task.Content)
	}
}

func (*Client) UnarchiveProject 

func (c *Client) UnarchiveProject(ctx context.Context, id string) error

UnarchiveProject restores an archived project.

func (*Client) UpdateComment 

func (c *Client) UpdateComment(ctx context.Context, id string, args UpdateCommentArgs) (Comment, error)

UpdateComment updates an existing comment.

func (*Client) UpdateLabel 

func (c *Client) UpdateLabel(ctx context.Context, id string, args UpdateLabelArgs) (Label, error)

UpdateLabel updates an existing label.

func (*Client) UpdateProject 

func (c *Client) UpdateProject(ctx context.Context, id string, args UpdateProjectArgs) (Project, error)

UpdateProject updates an existing project.

func (*Client) UpdateReminder 

func (c *Client) UpdateReminder(ctx context.Context, id string, args UpdateReminderArgs) (Reminder, error)

UpdateReminder updates an existing reminder.

func (*Client) UpdateSection 

func (c *Client) UpdateSection(ctx context.Context, id string, args UpdateSectionArgs) (Section, error)

UpdateSection updates an existing section.

func (*Client) UpdateTask 

func (c *Client) UpdateTask(ctx context.Context, id string, args UpdateTaskArgs) (Task, error)

UpdateTask updates an existing task and returns the updated resource.

func (*Client) UpdateWorkspace 

func (c *Client) UpdateWorkspace(ctx context.Context, id string, args UpdateWorkspaceArgs) (Workspace, error)

UpdateWorkspace updates an existing workspace.

type Collaborator 

type Collaborator struct {
	ID    string `json:"id"`
	Name  string `json:"name"`
	Email string `json:"email"`
}

Collaborator is a user who shares a project.

type Command 

type Command struct {
	Type   string `json:"type"`
	UUID   string `json:"uuid"`
	TempID string `json:"temp_id,omitempty"`
	Args   any    `json:"args"`
}

Command is a single write operation submitted to the Sync API. Multiple commands can be batched in one Sync call and may reference each other's temp_id values.

func NewCommand 

func NewCommand(commandType, tempID string, args any) Command

NewCommand builds a Command with a freshly generated UUID. Pass a non-empty tempID when the created object needs to be referenced by later commands in the same batch.

type Comment 

type Comment struct {
	ID         string      `json:"id"`
	TaskID     string      `json:"task_id"`
	ProjectID  string      `json:"project_id"`
	Content    string      `json:"content"`
	PostedAt   string      `json:"posted_at"`
	PostedUID  string      `json:"posted_uid"`
	Attachment *Attachment `json:"attachment"`
}

Comment is a comment on a task or project.

type CreateCommentArgs 

type CreateCommentArgs struct {
	Content    string      `json:"content"`
	TaskID     *string     `json:"task_id,omitempty"`
	ProjectID  *string     `json:"project_id,omitempty"`
	Attachment *Attachment `json:"attachment,omitempty"`
}

CreateCommentArgs are the parameters for creating a comment. Content and exactly one of TaskID or ProjectID are required.

type CreateLabelArgs 

type CreateLabelArgs struct {
	Name       string  `json:"name"`
	Color      *string `json:"color,omitempty"`
	Order      *int    `json:"order,omitempty"`
	IsFavorite *bool   `json:"is_favorite,omitempty"`
}

CreateLabelArgs are the parameters for creating a label. Name is required.

type CreateProjectArgs 

type CreateProjectArgs struct {
	Name       string  `json:"name"`
	ParentID   *string `json:"parent_id,omitempty"`
	Color      *string `json:"color,omitempty"`
	IsFavorite *bool   `json:"is_favorite,omitempty"`
	ViewStyle  *string `json:"view_style,omitempty"`
}

CreateProjectArgs are the parameters for creating a project. Name is required.

type CreateReminderArgs 

type CreateReminderArgs struct {
	ItemID      string  `json:"item_id"`
	Type        string  `json:"type"`
	DueString   *string `json:"due_string,omitempty"`
	DueDate     *string `json:"due_date,omitempty"`
	DueDatetime *string `json:"due_datetime,omitempty"`
	MinuteBias  *int    `json:"minute_offset,omitempty"`
	Name        *string `json:"name,omitempty"`
	LocLat      *string `json:"loc_lat,omitempty"`
	LocLong     *string `json:"loc_long,omitempty"`
	LocTrigger  *string `json:"loc_trigger,omitempty"`
	Radius      *int    `json:"radius,omitempty"`
}

CreateReminderArgs are the parameters for creating a reminder. ItemID and Type are required.

type CreateSectionArgs 

type CreateSectionArgs struct {
	Name      string `json:"name"`
	ProjectID string `json:"project_id"`
	Order     *int   `json:"order,omitempty"`
}

CreateSectionArgs are the parameters for creating a section. Name and ProjectID are required.

type CreateTaskArgs 

type CreateTaskArgs struct {
	Content      string   `json:"content"`
	Description  *string  `json:"description,omitempty"`
	ProjectID    *string  `json:"project_id,omitempty"`
	SectionID    *string  `json:"section_id,omitempty"`
	ParentID     *string  `json:"parent_id,omitempty"`
	Order        *int     `json:"order,omitempty"`
	Labels       []string `json:"labels,omitempty"`
	Priority     *int     `json:"priority,omitempty"`
	AssigneeID   *string  `json:"assignee_id,omitempty"`
	DueString    *string  `json:"due_string,omitempty"`
	DueDate      *string  `json:"due_date,omitempty"`
	DueDatetime  *string  `json:"due_datetime,omitempty"`
	DueLang      *string  `json:"due_lang,omitempty"`
	Deadline     *string  `json:"deadline_date,omitempty"`
	Duration     *int     `json:"duration,omitempty"`
	DurationUnit *string  `json:"duration_unit,omitempty"`
}

CreateTaskArgs are the parameters for creating a task. Content is required; pointer fields are omitted from the request when nil.

type CreateWorkspaceArgs 

type CreateWorkspaceArgs struct {
	Name        string  `json:"name"`
	Description *string `json:"description,omitempty"`
}

CreateWorkspaceArgs are the parameters for creating a workspace. Name is required.

type DayStats 

type DayStats struct {
	Date           string `json:"date"`
	TotalCompleted int    `json:"total_completed"`
}

DayStats holds completion counts for a single day.

type Deadline 

type Deadline struct {
	Date string `json:"date"`
	Lang string `json:"lang,omitempty"`
}

Deadline represents a task deadline (a full-day date).

type Due 

type Due struct {
	Date        string `json:"date"`
	String      string `json:"string"`
	Lang        string `json:"lang"`
	IsRecurring bool   `json:"is_recurring"`
	Timezone    string `json:"timezone,omitempty"`
}

Due represents the due date of a task.

type Duration 

type Duration struct {
	Amount int    `json:"amount"`
	Unit   string `json:"unit"`
}

Duration represents the estimated duration of a task.

type Error 

type Error struct {
	// StatusCode is the HTTP status code of the response.
	StatusCode int
	// Status is the HTTP status text of the response.
	Status string
	// Body is the raw response body, typically a JSON error payload.
	Body string
	// RetryAfter is populated from the Retry-After header on 429 responses.
	RetryAfter time.Duration
}

Error is returned for any non-2xx response from the Todoist API. It carries the HTTP status and the raw response body so callers can inspect the failure.

Example 
package main

import (
	"context"
	"errors"
	"fmt"
	"os"

	todoist "github.com/smirnoffmg/go-todoist"
)

func main() {
	api := todoist.New(os.Getenv("TODOIST_TOKEN"))

	_, err := api.GetTask(context.Background(), "does-not-exist")
	var apiErr *todoist.Error
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode)
		if apiErr.Temporary() {
			// Retry after apiErr.RetryAfter.
		}
	}
}

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Temporary 

func (e *Error) Temporary() bool

Temporary reports whether the error is likely transient (rate limiting or a server-side failure) and the request may succeed if retried.

type Filter 

type Filter struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	Query      string `json:"query"`
	Color      string `json:"color"`
	Order      int    `json:"item_order"`
	IsFavorite bool   `json:"is_favorite"`
}

Filter is a saved filter query.

The Todoist API v1 does not expose filters as REST endpoints; they are managed through the Sync API using the "filter_add", "filter_update" and "filter_delete" commands, and returned in SyncResponse.Filters when "filters" is among the requested resource types. See Sync and NewCommand.

type GetCommentsArgs 

type GetCommentsArgs struct {
	TaskID    string
	ProjectID string
	Cursor    string
	Limit     int
}

GetCommentsArgs controls listing of comments. Exactly one of TaskID or ProjectID must be set.

type GetLabelsArgs 

type GetLabelsArgs struct {
	Cursor string
	Limit  int
}

GetLabelsArgs controls listing and pagination of labels.

type GetProjectsArgs 

type GetProjectsArgs struct {
	Cursor string
	Limit  int
}

GetProjectsArgs controls listing and pagination of projects.

type GetRemindersArgs 

type GetRemindersArgs struct {
	Cursor string
	Limit  int
}

GetRemindersArgs controls listing and pagination of reminders.

type GetSectionsArgs 

type GetSectionsArgs struct {
	ProjectID string
	Cursor    string
	Limit     int
}

GetSectionsArgs controls listing and pagination of sections.

type GetTasksArgs 

type GetTasksArgs struct {
	ProjectID string
	SectionID string
	ParentID  string
	Label     string
	Cursor    string
	Limit     int
}

GetTasksArgs are the filters and pagination controls for listing tasks. All fields are optional.

type GetWorkspaceUsersArgs 

type GetWorkspaceUsersArgs struct {
	WorkspaceID string
	Cursor      string
	Limit       int
}

GetWorkspaceUsersArgs controls listing and pagination of workspace members.

type Label 

type Label struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	Color      string `json:"color"`
	Order      int    `json:"item_order"`
	IsFavorite bool   `json:"is_favorite"`
}

Label is a personal label.

type Option 

type Option func(*Client)

Option configures a Client.

func WithBaseURL 

func WithBaseURL(raw string) Option

WithBaseURL overrides the API base URL. Useful for testing against a stub server. The trailing slash, if any, is trimmed.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sets the underlying HTTP client used for requests.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header sent with each request.

type Page 

type Page[T any] struct {
	Results    []T    `json:"results"`
	NextCursor string `json:"next_cursor"`
}

Page is a single page of a cursor-paginated list response. NextCursor is empty when there are no further pages.

type ProductivityStats 

type ProductivityStats struct {
	KarmaLastUpdate float64        `json:"karma_last_update"`
	KarmaTrend      string         `json:"karma_trend"`
	Karma           float64        `json:"karma"`
	CompletedCount  int            `json:"completed_count"`
	DaysItems       []DayStats     `json:"days_items"`
	WeekItems       []WeekStats    `json:"week_items"`
	Goals           map[string]any `json:"goals"`
}

ProductivityStats holds the user's karma and completion statistics.

type Project 

type Project struct {
	ID             string `json:"id"`
	Name           string `json:"name"`
	Color          string `json:"color"`
	ParentID       string `json:"parent_id"`
	Order          int    `json:"child_order"`
	CommentCount   int    `json:"comment_count"`
	IsShared       bool   `json:"is_shared"`
	IsFavorite     bool   `json:"is_favorite"`
	IsInboxProject bool   `json:"is_inbox_project"`
	IsArchived     bool   `json:"is_archived"`
	ViewStyle      string `json:"view_style"`
	WorkspaceID    string `json:"workspace_id"`
	URL            string `json:"url"`
}

Project is a Todoist project.

type Reminder 

type Reminder struct {
	ID         string `json:"id"`
	ItemID     string `json:"item_id"`
	Type       string `json:"type"`
	Due        *Due   `json:"due"`
	MinuteBias int    `json:"minute_offset"`
	Name       string `json:"name"`
	LocLat     string `json:"loc_lat"`
	LocLong    string `json:"loc_long"`
	LocTrigger string `json:"loc_trigger"`
	Radius     int    `json:"radius"`
	IsDeleted  bool   `json:"is_deleted"`
}

Reminder is a reminder attached to a task.

type Section 

type Section struct {
	ID          string `json:"id"`
	ProjectID   string `json:"project_id"`
	Name        string `json:"name"`
	Order       int    `json:"section_order"`
	IsArchived  bool   `json:"is_archived"`
	WorkspaceID string `json:"workspace_id"`
}

Section is a section within a project.

type SyncRequest 

type SyncRequest struct {
	SyncToken     string
	ResourceTypes []string
	Commands      []Command
}

SyncRequest is the payload for a call to the Sync API. An empty SyncToken is sent as "*", requesting a full sync.

type SyncResponse 

type SyncResponse struct {
	SyncToken     string                     `json:"sync_token"`
	FullSync      bool                       `json:"full_sync"`
	SyncStatus    map[string]json.RawMessage `json:"sync_status"`
	TempIDMapping map[string]string          `json:"temp_id_mapping"`

	Projects  []Project  `json:"projects"`
	Items     []Task     `json:"items"`
	Sections  []Section  `json:"sections"`
	Labels    []Label    `json:"labels"`
	Notes     []Comment  `json:"notes"`
	Reminders []Reminder `json:"reminders"`
	Filters   []Filter   `json:"filters"`
	User      *User      `json:"user"`
}

SyncResponse is the result of a Sync API call. Only the resource slices relevant to the requested ResourceTypes are populated.

func (*SyncResponse) Err 

func (r *SyncResponse) Err() error

Err aggregates any per-command failures reported in SyncStatus. It returns nil when every command succeeded (status "ok") or when no commands were sent.

type TZInfo 

type TZInfo struct {
	Timezone  string `json:"timezone"`
	GMTString string `json:"gmt_string"`
	Hours     int    `json:"hours"`
	Minutes   int    `json:"minutes"`
	IsDST     int    `json:"is_dst"`
}

TZInfo is the user's timezone configuration.

type Task 

type Task struct {
	ID           string    `json:"id"`
	ProjectID    string    `json:"project_id"`
	SectionID    string    `json:"section_id"`
	ParentID     string    `json:"parent_id"`
	Content      string    `json:"content"`
	Description  string    `json:"description"`
	Priority     int       `json:"priority"`
	Labels       []string  `json:"labels"`
	Due          *Due      `json:"due"`
	Deadline     *Deadline `json:"deadline"`
	Duration     *Duration `json:"duration"`
	AssigneeID   string    `json:"assignee_id"`
	AssignerID   string    `json:"assigner_id"`
	Order        int       `json:"child_order"`
	CommentCount int       `json:"comment_count"`
	IsCompleted  bool      `json:"checked"`
	AddedAt      string    `json:"added_at"`
	CompletedAt  string    `json:"completed_at"`
	URL          string    `json:"url"`
}

Task is a Todoist task (an "item" in Sync API terms).

type UpdateCommentArgs 

type UpdateCommentArgs struct {
	Content string `json:"content"`
}

UpdateCommentArgs are the parameters for updating a comment.

type UpdateLabelArgs 

type UpdateLabelArgs struct {
	Name       *string `json:"name,omitempty"`
	Color      *string `json:"color,omitempty"`
	Order      *int    `json:"order,omitempty"`
	IsFavorite *bool   `json:"is_favorite,omitempty"`
}

UpdateLabelArgs are the parameters for updating a label. Only non-nil fields are sent.

type UpdateProjectArgs 

type UpdateProjectArgs struct {
	Name       *string `json:"name,omitempty"`
	Color      *string `json:"color,omitempty"`
	IsFavorite *bool   `json:"is_favorite,omitempty"`
	ViewStyle  *string `json:"view_style,omitempty"`
}

UpdateProjectArgs are the parameters for updating a project. Only non-nil fields are sent.

type UpdateReminderArgs 

type UpdateReminderArgs struct {
	Type        *string `json:"type,omitempty"`
	DueString   *string `json:"due_string,omitempty"`
	DueDate     *string `json:"due_date,omitempty"`
	DueDatetime *string `json:"due_datetime,omitempty"`
	MinuteBias  *int    `json:"minute_offset,omitempty"`
	Name        *string `json:"name,omitempty"`
}

UpdateReminderArgs are the parameters for updating a reminder.

type UpdateSectionArgs 

type UpdateSectionArgs struct {
	Name string `json:"name"`
}

UpdateSectionArgs are the parameters for updating a section.

type UpdateTaskArgs 

type UpdateTaskArgs struct {
	Content      *string  `json:"content,omitempty"`
	Description  *string  `json:"description,omitempty"`
	Labels       []string `json:"labels,omitempty"`
	Priority     *int     `json:"priority,omitempty"`
	AssigneeID   *string  `json:"assignee_id,omitempty"`
	DueString    *string  `json:"due_string,omitempty"`
	DueDate      *string  `json:"due_date,omitempty"`
	DueDatetime  *string  `json:"due_datetime,omitempty"`
	DueLang      *string  `json:"due_lang,omitempty"`
	Deadline     *string  `json:"deadline_date,omitempty"`
	Duration     *int     `json:"duration,omitempty"`
	DurationUnit *string  `json:"duration_unit,omitempty"`
}

UpdateTaskArgs are the parameters for updating a task. Only non-nil fields are sent, so the zero value leaves the task unchanged.

type UpdateWorkspaceArgs 

type UpdateWorkspaceArgs struct {
	Name        *string `json:"name,omitempty"`
	Description *string `json:"description,omitempty"`
}

UpdateWorkspaceArgs are the parameters for updating a workspace.

type User 

type User struct {
	ID           string  `json:"id"`
	Email        string  `json:"email"`
	FullName     string  `json:"full_name"`
	InboxID      string  `json:"inbox_project_id"`
	TZInfo       TZInfo  `json:"tz_info"`
	Lang         string  `json:"lang"`
	DateFormat   int     `json:"date_format"`
	TimeFormat   int     `json:"time_format"`
	StartDay     int     `json:"start_day"`
	Karma        float64 `json:"karma"`
	IsPremium    bool    `json:"is_premium"`
	PremiumUntil string  `json:"premium_until"`
	AvatarBig    string  `json:"avatar_big"`
}

User is the authenticated user's profile.

type WeekStats 

type WeekStats struct {
	From           string `json:"from"`
	To             string `json:"to"`
	TotalCompleted int    `json:"total_completed"`
}

WeekStats holds completion counts for a single week.

type Workspace 

type Workspace struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Role        string `json:"role"`
	Plan        string `json:"current_active_plan"`
	IsGuest     bool   `json:"is_guest_allowed"`
	MemberCount int    `json:"member_count"`
	LogoBig     string `json:"logo_big"`
}

Workspace is a Todoist workspace (team space).

type WorkspaceUser 

type WorkspaceUser struct {
	UserID      string `json:"user_id"`
	WorkspaceID string `json:"workspace_id"`
	UserEmail   string `json:"user_email"`
	FullName    string `json:"full_name"`
	Role        string `json:"role"`
	ImageID     string `json:"image_id"`
}

WorkspaceUser is a member of a workspace.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.