113 lines
4.4 KiB
Markdown
113 lines
4.4 KiB
Markdown
|
# Graph API reference for Microsoft To Do
|
||
|
|
|
||
|
|
Quick reference for the parts of the Microsoft Graph To Do API this skill relies
|
||
|
|
on. Full docs: <https://learn.microsoft.com/graph/api/resources/todo-overview>.
|
||
|
|
|
||
|
|
## Object model
|
||
|
|
|
||
|
|
```
|
||
|
|
/me/todo/lists todoTaskList[] (the task lists)
|
||
|
|
/me/todo/lists/{listId}/tasks todoTask[] (tasks in a list)
|
||
|
|
/me/todo/lists/{listId}/tasks/{taskId}/checklistItems checklistItem[] (subtasks)
|
||
|
|
```
|
||
|
|
|
||
|
|
- **List ids** are long opaque strings (base64-ish), *not* GUIDs. Resolve by
|
||
|
|
display name when you can.
|
||
|
|
- **Task ids** and **checklist item ids** are also opaque strings returned by the
|
||
|
|
API; pass them back verbatim.
|
||
|
|
|
||
|
|
## todoTask properties (create / update)
|
||
|
|
|
||
|
|
`--fields` (and the convenience flags) map to these `todoTask` properties:
|
||
|
|
|
||
|
|
| Property | JSON value | Notes / example |
|
||
|
|
|---|---|---|
|
||
|
|
| `title` | string | **Required on create.** `{"title":"Buy milk"}` |
|
||
|
|
| `body` | `{ "content": "...", "contentType": "text"\|"html" }` | `--body` builds the `text` form |
|
||
|
|
| `importance` | `"low"` \| `"normal"` \| `"high"` | enum — exact strings |
|
||
|
|
| `status` | `"notStarted"` \| `"inProgress"` \| `"completed"` \| `"waitingOnOthers"` \| `"deferred"` | enum |
|
||
|
|
| `dueDateTime` | `dateTimeTimeZone` (see below) | `--due` builds this |
|
||
|
|
| `startDateTime` | `dateTimeTimeZone` | `--start` builds this |
|
||
|
|
| `reminderDateTime` | `dateTimeTimeZone` | set `isReminderOn:true` too (`--reminder` does both) |
|
||
|
|
| `isReminderOn` | boolean | |
|
||
|
|
| `categories` | array of strings | must match category names defined in the user's Outlook |
|
||
|
|
| `recurrence` | `patternedRecurrence` object | advanced; pass via `--fields` |
|
||
|
|
|
||
|
|
Read-only properties returned on GET (don't send them on write):
|
||
|
|
`id`, `createdDateTime`, `lastModifiedDateTime`, `completedDateTime`,
|
||
|
|
`hasAttachments`.
|
||
|
|
|
||
|
|
### `dateTimeTimeZone` shape
|
||
|
|
|
||
|
|
Date/time properties are **not** plain ISO strings — they're an object:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{ "dueDateTime": { "dateTime": "2026-07-01T17:00:00", "timeZone": "UTC" } }
|
||
|
|
```
|
||
|
|
|
||
|
|
The CLI's `--due` / `--start` / `--reminder` accept `2026-07-01` (→ midnight) or a
|
||
|
|
full `2026-07-01T17:00:00`, and wrap it using `TODO_TIMEZONE` (default `UTC`). The
|
||
|
|
`timeZone` accepts IANA (`America/Denver`) or Windows (`Mountain Standard Time`)
|
||
|
|
zone names. To set one manually via `--fields`, supply the full object.
|
||
|
|
|
||
|
|
### Marking complete
|
||
|
|
|
||
|
|
Set `status` to `"completed"` (the `done` command does this). Graph stamps
|
||
|
|
`completedDateTime` automatically. Setting status back to `notStarted`/
|
||
|
|
`inProgress` reopens it.
|
||
|
|
|
||
|
|
## Querying tasks (OData)
|
||
|
|
|
||
|
|
The CLI maps flags to OData query options on `/me/todo/lists/{listId}/tasks`:
|
||
|
|
|
||
|
|
- `--filter` → `$filter`. To Do supports a subset of OData. Useful ones:
|
||
|
|
- `status ne 'completed'` — open tasks
|
||
|
|
- `status eq 'completed'`
|
||
|
|
- `importance eq 'high'`
|
||
|
|
- `lastModifiedDateTime gt 2026-06-01T00:00:00Z`
|
||
|
|
- combine with `and` / `or`
|
||
|
|
- Note: filtering directly on `dueDateTime` is limited; prefer fetching and
|
||
|
|
sorting client-side for due-date views.
|
||
|
|
- `--orderby` → `$orderby`, e.g. `dueDateTime/dateTime asc` (nested path), or
|
||
|
|
`importance desc`, `lastModifiedDateTime desc`, `createdDateTime asc`.
|
||
|
|
- `--select` → projects which properties come back: `title,status,dueDateTime`.
|
||
|
|
- `--top` → page size; `--all` follows `@odata.nextLink` to return every page.
|
||
|
|
|
||
|
|
### Escaping quotes
|
||
|
|
|
||
|
|
OData string literals use single quotes; a literal single quote is doubled:
|
||
|
|
`title eq 'O''Brien'`. In the shell, wrap the whole `--filter` value in double
|
||
|
|
quotes.
|
||
|
|
|
||
|
|
## Checklist items (subtasks)
|
||
|
|
|
||
|
|
A `checklistItem` has just `displayName` and `isChecked`:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
node scripts/todo.mjs checklist-add --list "Work" --id "<TASK_ID>" --name "Draft outline"
|
||
|
|
node scripts/todo.mjs checklist-check --list "Work" --id "<TASK_ID>" --item "<ITEM_ID>" # --uncheck to undo
|
||
|
|
```
|
||
|
|
|
||
|
|
## Response shape (reads)
|
||
|
|
|
||
|
|
Reads return tasks simplified to:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"id": "<opaque task id>",
|
||
|
|
"title": "Renew SSL cert",
|
||
|
|
"status": "inProgress",
|
||
|
|
"importance": "high",
|
||
|
|
"isReminderOn": true,
|
||
|
|
"dueDateTime": { "dateTime": "2026-07-01T00:00:00.0000000", "timeZone": "UTC" },
|
||
|
|
"reminderDateTime": { "dateTime": "2026-06-30T09:00:00.0000000", "timeZone": "UTC" },
|
||
|
|
"body": { "content": "Use the prod ACME account", "contentType": "text" },
|
||
|
|
"categories": [],
|
||
|
|
"createdDateTime": "2026-06-16T10:00:00Z",
|
||
|
|
"lastModifiedDateTime": "2026-06-16T12:30:00Z"
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
`id` is the value you pass to `get`, `update`, `done`, and `delete`. Empty/unset
|
||
|
|
properties are omitted from the simplified shape.
|