todoist-api

Todoist API v1 — Developer Reference

Always load the detailed references when working with the Todoist API:

• references/api-endpoints.md — all REST endpoints for tasks, projects, sections, labels, comments, filters
• references/sync-endpoint.md — sync endpoint for batched reads and writes with incremental sync
• references/authentication.md — OAuth2 flow, scopes, personal tokens, short-lived extension tokens
• references/webhooks.md — webhook registration, event types, HMAC verification, payload structure
• references/data-models.md — complete field-by-field schemas for all Todoist objects

Quick Reference

API Base URL

https://api.todoist.com/api/v1

Authentication

All requests require: Authorization: Bearer {token}

Token sources:

• Personal API token — from Todoist Settings > Integrations > Developer
• OAuth token — from OAuth2 flow (see references/authentication.md)
• Short-lived token — from x-todoist-apptoken header in UI extension requests

Core Endpoints

Method	Endpoint	Description
GET	/tasks	List tasks (filterable by project, section)
POST	/tasks	Create a task
GET	/tasks/{id}	Get a task
POST	/tasks/{id}	Update a task
DELETE	/tasks/{id}	Delete a task
POST	/tasks/{id}/close	Complete a task
POST	/tasks/{id}/reopen	Reopen a task
GET	/projects	List projects
POST	/projects	Create a project
GET	/projects/{id}	Get a project
POST	/projects/{id}	Update a project
DELETE	/projects/{id}	Delete a project
GET	/sections	List sections
POST	/sections	Create a section
GET	/labels	List labels
POST	/labels	Create a label
GET	/comments	List comments (by task_id or project_id)
POST	/comments	Create a comment
POST	/sync	Sync endpoint (read/write batched)

Pagination

All list endpoints use cursor-based pagination:

• Send limit parameter (default varies by endpoint)
• Response includes next_cursor — pass as cursor in next request
• When next_cursor is null, no more results

OAuth Scopes

Scope	Access Level
task:add	Create tasks only
data:read	Read all data
data:read_write	Read and write all data
data:delete	Delete tasks, comments, etc.
project:delete	Delete projects
backups:read	Access user backups

Key Data Model Facts

• All IDs are strings (not numbers) in API v1
• Task priority: 1 (normal) to 4 (urgent)
• due object: date (YYYY-MM-DD), optional time (HH:mm), optional timezone (IANA)
• deadline is separate from due — use for hard deadlines distinct from scheduling
• duration: amount (number) + unit ("minute" | "hour" | "day")
• Colors are string identifiers: "berry_red", "red", "orange", "yellow", "olive_green", "lime_green", "green", "mint_green", "teal", "sky_blue", "light_blue", "blue", "grape", "violet", "lavender", "magenta", "salmon", "charcoal", "grey", "taupe"

Error Response Format

{
  "error_tag": "INVALID_ARGUMENT_VALUE",
  "error_code": 40,
  "error": "Invalid argument value",
  "http_code": 400,
  "error_extra": {
    "argument": "priority",
    "explanation": "must be between 1 and 4"
  }
}

Handle 429 (rate limit) using error_extra.retry_after for backoff.