会话创建
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 数据
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Todoist API Skill
Interact with the Todoist REST API v2 via `curl` and `jq`.
## Authentication
Resolve the API token in order:
1. Environment variable `TODOIST_API_TOKEN`
2. User-provided token in conversation
3. Ask the user (token is at: Todoist Settings → Integrations → Developer)
```bash
[ -n "$TODOIST_API_TOKEN" ] && echo "Token available" || echo "Token not set"
```
All requests use Bearer auth:
```bash
curl -s -H "Authorization: Bearer $TODOIST_API_TOKEN" \
"https://api.todoist.com/rest/v2/ENDPOINT"
```
POST requests add Content-Type:
```bash
curl -s -X POST \
-H "Authorization: Bearer $TODOIST_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"key": "value"}' \
"https://api.todoist.com/rest/v2/ENDPOINT"
```
## Base URL
`https://api.todoist.com/rest/v2/`
## Confirmation Requirement
**Before executing any destructive action (DELETE, close, update, archive), ask the user for confirmation.** A single confirmation covers a logical group of related actions.
Destructive: delete, close/complete, update, archive.
Read-only (GET): no confirmation needed.
## Priority Mapping
⚠️ **The API and UI use inverted priority numbers:**
| UI Label | API `priority` field | Filter syntax |
|----------|---------------------|---------------|
| P1 (urgent, red) | `4` | `p1` |
| P2 (high, orange) | `3` | `p2` |
| P3 (medium, blue) | `2` | `p3` |
| P4 (normal, none) | `1` | `p4` |
When creating/updating tasks, use the **API value** (4 = urgent).
When using filter queries, use the **UI label** (`p1` = urgent).
## Task Links (v2 IDs)
⚠️ **The REST API `url` field uses deprecated numeric IDs.** Todoist deprecated `/app/task/<numeric_id>` URLs (end of 2025). The new format uses alphanumeric v2 IDs.
**New URL format:** `https://app.todoist.com/app/task/<v2_id>`
The REST API v2 does NOT return `v2_id`. Use the Sync API v9 to get it:
### Get v2_id for a single task
```bash
curl -s -X POST \
-H "Authorization: Bearer $TODOIST_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"item_id": "TASK_ID"}' \
"https://api.todoist.com/sync/v9/items/get" | jq '.item.v2_id'
```
Works with both numeric IDs and v2_ids as input.
### Get v2_ids for all tasks (bulk)
```bash
curl -s -X POST \
-H "Authorization: Bearer $TODOIST_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"sync_token": "*", "resource_types": ["items"]}' \
"https://api.todoist.com/sync/v9/sync" | jq '[.items[] | {id, v2_id, content}]'
```
### Build a task link
```bash
# After getting v2_id from Sync API:
TASK_ID="9971910530"
V2_ID=$(curl -s -X POST \
-H "Authorization: Bearer $TODOIST_API_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"item_id\": \"$TASK_ID\"}" \
"https://api.todoist.com/sync/v9/items/get" | jq -r '.item.v2_id')
echo "https://app.todoist.com/app/task/$V2_ID"
```
### Efficient bulk pattern (REST + Sync combo)
When listing multiple tasks, do ONE Sync call for the v2_id map instead of N individual lookups:
```bash
# 1. Get tasks via REST API (for filtering)
TASKS=$(curl -s -H "Authorization: Bearer $TODOIST_API_TOKEN" \
"https://api.todoist.com/rest/v2/tasks?filter=today")
# 2. Build v2_id lookup from Sync API (one call)
V2_MAP=$(curl -s -X POST \
-H "Authorization: Bearer $TODOIST_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"sync_token": "*", "resource_types": ["items"]}' \
"https://api.todoist.com/sync/v9/sync" | jq '[.items[] | {(.id): .v2_id}] | add')
# 3. Merge: replace URLs with v2 format
echo "$TASKS" | jq --argjson map "$V2_MAP" '
[.[] | . + {link: "https://app.todoist.com/app/task/\($map[.id])"}]
'
```
**When presenting task links to the user, always use v2_id URLs.** Never use the `url` field from the REST API directly.
## Task Response Object
The REST API returns tasks with this structure:
```json
{
"id": "123456789",
"content": "Task name",
"description": "Additional details",
"comment_count": 0,
"is_completed": false,
"order": 1,
"priority": 1,
"project_id": "987654321",
"section_id": null,
"parent_id": null,
"labels": [],
"creator_id": "111",
"created_at": "2024-01-15T10:30:00.000000Z",
"assignee_id": null,
"assigner_id": null,
"url": "https://app.todoist.com/app/task/123456789",
"duration": null,
"deadline": null,
"due": {
"date": "2024-01-20",
"string": "every monday",
"lang": "en",
"is_recurring": true
}
}
```
**Note:** The `url` field uses deprecated numeric IDs. See "Task Links (v2 IDs)" above for the correct URL format.
### The `due` object
| Field | Type | Description |
|-------|------|-------------|
| `date` | string | `YYYY-MM-DD` or RFC3339 datetime |
| `string` | string | Human-readable recurrence/date text |
| `lang` | string | Language code |
| `is_recurring` | boolean | Whether the task recurs |
`due` is `null` if no due date is set.
### The `deadline` field
A hard deadline separate from `due`. When both are set, `due` is the soft/scheduled date and `deadline` is the hard cutoff. Can be set via `deadline_date` (YYYY-MM-DD) or `deadline_datetime` (RFC3339) when creating/updating tasks.
## Endpoints Reference
### Tasks
| Operation | Method | Endpoint |
|-----------|--------|----------|
| List active tasks | GET | `/tasks` |
| Get task | GET | `/tasks/{id}` |
| Create task | POST | `/tasks` |
| Update task | POST | `/tasks/{id}` |
| Close task | POST | `/tasks/{id}/close` |
| Reopen task | POST | `/tasks/{id}/reopen` |
| Delete task | DELETE | `/tasks/{id}` |
**Task filters** (query params for GET /tasks):
- `project_id` — filter by project
- `section_id` — filter by section
- `label` — filter by label name
- `filter` — Todoist filter query (e.g. `today`, `overdue`). See `references/filters.md`
**Task creation/update fields:**
- `content` (required for creation) — task text
- `description` — additional details
- `project_id`, `section_id`, `parent_id` — organization
- `priority` — 1 (normal) to 4 (urgent). **See Priority Mapping above**
- `due_string` — natural language ("tomorrow", "every monday")
- `due_date` — YYYY-MM-DD
- `due_datetime` — RFC3339
- `deadline_date` — YYYY-MM-DD hard deadline
- `deadline_datetime` — RFC3339 hard deadline
- `labels` — array of label names
- `assignee_id` — for shared projects
- `duration`, `duration_unit` — estimated time
### Projects
| Operation | Method | Endpoint |
|-----------|--------|----------|
| List projects | GET | `/projects` |
| Get project | GET | `/projects/{id}` |
| Create project | POST | `/projects` |
| Update project | POST | `/projects/{id}` |
| Archive project | POST | `/projects/{id}/archive` |
| Unarchive project | POST | `/projects/{id}/unarchive` |
| Delete project | DELETE | `/projects/{id}` |
| List collaborators | GET | `/projects/{id}/collaborators` |
**Project fields:** `name` (required), `parent_id`, `color` (e.g. "berry_red", "blue"), `is_favorite`, `view_style` ("list" or "board")
### Sections
| Operation | Method | Endpoint |
|-----------|--------|----------|
| List sections | GET | `/sections` |
| Get section | GET | `/sections/{id}` |
| Create section | POST | `/sections` |
| Update section | POST | `/sections/{id}` |
| Delete section | DELETE | `/sections/{id}` |
**Section fields:** `name` (required), `project_id` (required for creation), `order`
### Labels
| Operation | Method | Endpoint |
|-----------|--------|----------|
| List personal labels | GET | `/labels` |
| Get label | GET | `/labels/{id}` |
| Create label | POST | `/labels` |
| Update label | POST | `/labels/{id}` |
| Delete label | DELETE | `/labels/{id}` |
**Label fields:** `name` (required), `color`, `order`, `is_favorite`
### Comments
| Operation | Method | Endpoint |
|-----------|--------|----------|
| List comments | GET | `/comments` |
| Get comment | GET | `/comments/{id}` |
| Create comment | POST | `/comments` |
| Update comment | POST | `/comments/{id}` |
| Delete comment | DELETE | `/comments/{id}` |
**Comment query params:** `task_id` or `project_id` (one required for listing)
**Comment fields:** `content` (required, markdown supported), `task_id` or `project_id` (one required for creation)
## Pagination
**Most REST v2 endpoints (tasks, projects, sections, labels) return flat JSON arrays — no pagination needed.**
Pagination with cursors applies only to specific endpoints like completed tasks (API v1). See `references/completed-tasks.md` for the cursor-based pagination pattern.
## Common Patterns
### Create a task with due date
```bash
curl -s -X POST \
-H "Authorization: Bearer $TODOIST_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content": "Buy milk", "due_string": "tomorrow", "priority": 4}' \
"https://api.todoist.com/rest/v2/tasks"
```
Note: `priority: 4` = urgent (P1 in UI).
### Get today's tasks
```bash
curl -s -H "Authorization: Bearer $TODOIST_API_TOKEN" \
"https://api.todoist.com/rest/v2/tasks?filter=today" | jq '.'
```
### Get overdue tasks
```bash
curl -s -H "Authorization: Bearer $TODOIST_API_TOKEN" \
"https://api.todoist.com/rest/v2/tasks?filter=overdue" | jq '.'
```
### Complete a task
```bash
curl -s -X POST \
-H "Authorization: Bearer $TODOIST_API_TOKEN" \
"https://api.todoist.com/rest/v2/tasks/TASK_ID/close"
```
### List all tasks in a project
```bash
curl -s -H "Authorization: Bearer $TODOIST_API_TOKEN" \
"https://api.todoist.com/rest/v2/tasks?project_id=PROJECT_ID" | jq '.'
```
## Error Handling
| Code | Meaning |
|------|---------|
| 200 | Success with body |
| 204 | Success, no content |
| 400 | Bad request |
| 401 | Auth failed |
| 403 | Forbidden |
| 404 | Not found |
| 429 | Rate limited (wait + retry) |
| 5xx | Server error (safe to retry) |
```bash
response=$(curl -s -w "\n%{http_code}" \
-H "Authorization: Bearer $TODOIST_API_TOKEN" \
"https://api.todoist.com/rest/v2/tasks")
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')
if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
echo "$body" | jq '.'
else
echo "Error: HTTP $http_code"
echo "$body"
fi
```
## Idempotency
For safe retries on writes, include `X-Request-Id` (max 36 chars):
```bash
curl -s -X POST \
-H "Authorization: Bearer $TODOIST_API_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Request-Id: $(uuidgen)" \
-d '{"content": "New task"}' \
"https://api.todoist.com/rest/v2/tasks"
```
## Completed Tasks
REST v2 `/tasks` returns only active tasks. For completed task history, see `references/completed-tasks.md`.
## Additional Reference
- `references/completed-tasks.md` — completed task history (API v1 endpoints, cursor pagination)
- `references/filters.md` — Todoist filter query syntax
---
> Source: [aneym/agent-skills](https://github.com/aneym/agent-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
认证
基本网址
确认要求
优先级映射
任务链接(v2 ID)
文件/命令 -> curl · TODOIST_API_TOKEN · https://api.todoist.com/rest/v2/ · priority · url · /app/task/<numeric_id> · https://app.todoist.com/app/task/<v2_id> · v2_id
内容校验值 -> d71d8e098b40
当前原文的自动摘译,尚未人工审校。
认证
按顺序解析 API 令牌: 环境变量
TODOIST_API_TOKEN对话中用户提供的令牌 询问用户(令牌位于:Todoist 设置 → 集成 → 开发人员) 所有请求都使用不记名身份验证:基本网址
https://api.todoist.com/rest/v2/确认要求
在执行任何破坏性操作(删除、关闭、更新、存档)之前,请要求用户确认。单个确认涵盖一组相关操作的逻辑。破坏性:删除、关闭/完成、更新、存档。只读 (GET):无需确认。
优先级映射
⚠️ API 和 UI 使用倒置优先级数字: UI 标签 · API
priority字段 · 过滤器语法 P1(紧急,红色) ·4·p1P2(高,橙色) ·3·p2P3(中,蓝色) ·2·p3任务链接(v2 ID)
⚠️ REST API
url字段使用已弃用的数字 ID。 Todoist 已弃用/app/task/<numeric_id>URL(2025 年底)。新格式使用字母数字 v2 ID。新 URL 格式:https://app.todoist.com/app/task/<v2_id>REST API v2 不会返回v2_id。使用 Sync API v9 获取它: