Todoist Api
Pull Todoist completed-task history from the shell or REST API for retros, reporting, and agent workflows that need done-work context.
Overview
Todoist-api is an agent skill for the Build phase that retrieves Todoist completed tasks via the `td completed` CLI and Todoist API v1.
Install
npx skills add https://github.com/intellectronica/agent-skills --skill todoist-apiWhat is this skill?
- `td completed` with `--since`/`--until`, project filter, `--json`, `--ndjson`, and `--full` output modes
- Default `--limit` of 300 results; `--all` for uncapped fetches
- Direct API v1: completed tasks by completion date and by due date via Bearer token
- Supports today's completed tasks as the default CLI window without extra flags
- Default CLI `--limit` of 300 completed tasks
- Todoist API v1 `tasks/completed` by completion date and by due date
Adoption & trust: 1.3k installs on skills.sh; 270 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need machine-readable Todoist completion history for an agent or script, but only know how to browse finished tasks in the app.
Who is it for?
Solo builders who already use Todoist and want shell- or agent-driven completion reports and automation inputs.
Skip if: Teams that need full CRUD on active tasks, OAuth onboarding walkthroughs, or Todoist REST v2-only features not covered in this readme.
When should I use this skill?
You need Todoist completed tasks for today, a date range, or a named project via CLI JSON or direct API calls.
What do I get? / Deliverables
You get dated, project-filtered completed-task JSON (or ndjson) from the CLI or curl-ready API calls without manual export.
- Shell commands for `td completed`
- curl examples for API v1 completed endpoints
- JSON or ndjson completion datasets
Recommended Skills
Journey fit
Canonical shelf for third-party API and CLI integration skills that wire external services into your build stack. Documents `td completed` and Todoist API v1 completed-task endpoints—not generic task creation—so it belongs on the integrations shelf.
How it compares
Use for read-only completed-task retrieval—not as a full Todoist project-management or inbox skill.
Common Questions / FAQ
Who is todoist-api for?
Indie builders and agents that automate around Todoist and need completed-task exports by date, project, or API endpoint.
When should I use todoist-api?
During Build integrations when wiring retros or reports, and in Grow or Operate when you need JSON of what was finished since a given day or within a project.
Is todoist-api safe to install?
It expects a Todoist API token in the environment; review the Security Audits panel on this page before granting network and secrets access in your agent.
SKILL.md
READMESKILL.md - Todoist Api
# Retrieving Completed Tasks The `td completed` command is the primary way to retrieve completed tasks. ## CLI Usage ### Basic Usage ```bash td completed # Today's completed tasks td completed --json # JSON output td completed --all --json # All completed (no limit) ``` ### Date Range ```bash td completed --since 2024-01-01 --until 2024-01-31 td completed --since 2024-01-01 --json ``` ### Filter by Project ```bash td completed --project "Work" --json ``` ### Options - `--since <date>` - Start date (YYYY-MM-DD), default: today - `--until <date>` - End date (YYYY-MM-DD), default: tomorrow - `--project <name>` - Filter by project name - `--limit <n>` - Limit number of results (default: 300) - `--all` - Fetch all results (no limit) - `--json` - Output as JSON - `--ndjson` - Output as newline-delimited JSON - `--full` - Include all fields in JSON output ## Alternative: Direct API Access If you need more control or the CLI doesn't provide the required functionality, you can use the API directly. ### API v1 Endpoints **By Completion Date:** ```bash curl -s -H "Authorization: Bearer $TODOIST_API_TOKEN" \ "https://api.todoist.com/api/v1/tasks/completed/by_completion_date?since=2024-01-01T00:00:00Z&until=2024-01-31T23:59:59Z" ``` **By Due Date:** ```bash curl -s -H "Authorization: Bearer $TODOIST_API_TOKEN" \ "https://api.todoist.com/api/v1/tasks/completed/by_due_date?since=2024-01-01T00:00:00Z" ``` ### API Parameters - `since` - Start date (ISO 8601 format) - `until` - End date (ISO 8601 format) - `project_id` - Filter by project ID - `limit` - Results per page - `cursor` - Pagination cursor ### Response Structure Completed task objects include: ```json { "id": "123456789", "content": "Task content", "project_id": "987654321", "completed_at": "2024-06-15T14:30:00Z", "meta_data": null } ``` ## Notes - Completed tasks are stored in history and may have limited retention based on user plan - Use `td task uncomplete id:xxx` to reopen a completed task - Recurring tasks create new instances when completed; the original remains in history # Todoist Filter Query Syntax The `--filter` flag on `td task list` accepts Todoist's filter query language, enabling powerful task queries. ## Usage with td CLI ```bash td task list --filter "today & p1" td task list --filter "overdue | today" --json td task list --filter "#Work & @urgent" --all ``` ## Basic Filters | Filter | Description | |--------|-------------| | `today` | Tasks due today | | `tomorrow` | Tasks due tomorrow | | `overdue` | Overdue tasks | | `no date` | Tasks without a due date | | `7 days` | Tasks due within the next 7 days | | `next week` | Tasks due next week | | `recurring` | Recurring tasks only | ## Date Filters | Filter | Description | |--------|-------------| | `due before: Jan 1` | Due before specific date | | `due after: Jan 1` | Due after specific date | | `due: Jan 1` | Due on specific date | | `created: today` | Created today | | `created before: -7 days` | Created more than 7 days ago | ## Priority Filters | Filter | Description | |--------|-------------| | `p1` | Priority 1 (urgent) | | `p2` | Priority 2 (high) | | `p3` | Priority 3 (medium) | | `p4` or `no priority` | Priority 4 (normal) | ## Label Filters | Filter | Description | |--------|-------------| | `@label_name` | Tasks with specific label | | `no labels` | Tasks without any labels | ## Project and Section Filters | Filter | Description | |--------|-------------| | `#Project Name` | Tasks in specific project | | `##Project Name` | Tasks in project and subprojects | | `/Section Name` | Tasks in specific section | ## Assignment Filters | Filter | Description | |--------|-------------| | `assigned to: me` | Tasks assigned to you | | `assigned to: John` | Tasks assigned to John | | `assigned by: me` | Tasks you assigned | | `assigned` | All assigned tasks | ## Combining Filters Use logical operators to combine filters: | Oper