canonical: https://jentic.com/apis/googleapis.com/tasks

# Google Tasks API

The Google Tasks API exposes the same tasks and task lists that surface inside Gmail, Google Calendar, and the Tasks mobile apps. Programs can create lists, add and update individual tasks, mark them complete, reorder them with the move action, and clear completed items in bulk. It is the integration surface for AI assistants, calendar add-ons, and productivity tools that need to read or write a user's personal task backlog without scraping the UI.

## For AI agents

Read and write a Google user's task lists and tasks - create tasks, mark them complete, reorder, and clear lists across the user's account.

## Scope

Does not handle calendar events, reminders for non-Tasks surfaces, or shared team task management - use for personal Google Tasks lists only.

## Capabilities

- Create, update, and complete individual tasks within a user's task list
- List all task lists for the authenticated user
- Reorder tasks within a list using the move action
- Clear all completed tasks from a list in a single call
- Insert subtasks under a parent task with hierarchical structure
- Filter tasks by completion status, due date, or last-modified time

## Use cases

### AI Assistant Task Capture

An AI assistant transcribing a meeting extracts action items and writes them straight into the user's Google Tasks list. The assistant calls insert under /tasks/v1/lists/{tasklist}/tasks for each action item with a title, due date, and notes field referencing the meeting. The user sees the captured tasks appear in Gmail, Calendar, and the Tasks mobile app within seconds.

Example prompt: POST /tasks/v1/lists/@default/tasks with title='Send proposal to Acme', due='2026-06-17T17:00:00Z', and notes containing the source meeting link.

### Cross-Tool Task Sync

A productivity dashboard syncs tasks bidirectionally between Google Tasks and a project management tool. The integration polls /tasks/v1/lists/{tasklist}/tasks with the updatedMin parameter to retrieve recently changed tasks, then mirrors them to the other system. Completion-state changes flow through patch calls so users can mark tasks done in either tool.

Example prompt: GET /tasks/v1/lists/{tasklist}/tasks?updatedMin=2026-06-10T00:00:00Z and for each modified task issue a PATCH against the corresponding task in the other system.

### Workspace Onboarding Task Templates

An HR onboarding workflow creates a personalised task list for each new hire on day one. The system creates a fresh task list under the new hire's account, inserts a sequence of onboarding tasks (read handbook, set up dev environment, schedule 1:1s) with due dates spread over the first two weeks, and shares progress visibility with the manager. Existing employees see their onboarding tasks in the Google Tasks side panel inside Gmail.

Example prompt: Create a new tasklist via POST /tasks/v1/users/@me/lists named 'Onboarding Week 1', then insert 8 child tasks under it with sequential due dates.

### Agent-Maintained Daily Plan via Jentic

An AI agent acts as a personal daily planner. Each morning it lists yesterday's incomplete tasks, reschedules them with new due dates, clears completed items, and inserts new tasks based on calendar events scraped from Calendar API. Through Jentic the agent's OAuth token is held in the vault and refreshed automatically across runs.

Example prompt: Through Jentic, search 'add a task to google tasks', load POST /tasks/v1/lists/@default/tasks, and execute it for each action item the agent generated overnight.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /tasks/v1/users/@me/lists | List all task lists for the authenticated user |
| POST | /tasks/v1/users/@me/lists | Create a new task list |
| GET | /tasks/v1/lists/{tasklist}/tasks | List tasks within a list |
| POST | /tasks/v1/lists/{tasklist}/tasks | Insert a new task into a list |
| POST | /tasks/v1/lists/{tasklist}/tasks/{task}/move | Move a task to a new position or under a different parent |
| POST | /tasks/v1/lists/{tasklist}/clear | Clear all completed tasks from a list |

## Key resources

- **TaskList** — Named container for tasks; users typically have one default list plus custom lists
- **Task** — Individual to-do item with title, notes, due date, status, and optional parent for subtasks

## Why Jentic

- **Setup:** Wiring the Google Tasks API by hand means setting up Google OAuth, requesting the tasks scope, handling task-list and task path parameters, and refreshing tokens yourself. Through Jentic you install once, import the Google Tasks API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** Google Tasks puts the task list in the URL path (/tasks/v1/lists/{tasklist}/tasks), so a rule can pin your agent to one task list: it can read and add tasks there and nothing else. You choose the operations it may call, so destructive ones like clearing completed tasks or list deletion are not included unless you add them.
- **Credential handling:** Your Google Tasks OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add a task to google tasks' or 'list my google tasks', and Jentic returns the matching Tasks v1 operation with its input schema, including the tasklist id and task body, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Google Calendar API** — Tasks can be displayed alongside Calendar events; Calendar events often generate follow-up tasks
- **Gmail API** — Convert email threads into actionable Tasks with deep links back to the source message
- **Google Keep API** — Note-taking surface that also supports checkboxes; suited for free-form lists rather than scheduled tasks

## FAQ

### What authentication does the Google Tasks API use?

Google Tasks uses OAuth 2.0 with two scopes - https://www.googleapis.com/auth/tasks for full read/write and https://www.googleapis.com/auth/tasks.readonly for view-only access. Choose the readonly scope when your integration only lists tasks. Through Jentic, the OAuth tokens are stored encrypted and refresh transparently, so the agent never handles raw bearer tokens.

### Can I create subtasks with the Google Tasks API?

Yes. Insert a child task with POST /tasks/v1/lists/{tasklist}/tasks and pass the parent parameter set to the parent task's ID, or use the move endpoint with parent and previous parameters to nest an existing task. The Tasks mobile app and Gmail side panel render the resulting hierarchy as nested checkboxes.

### What are the rate limits for the Google Tasks API?

The default per-project quota is 50,000 queries per day with a per-user limit of approximately 5 queries per second. Tasks resources are small so most integrations stay well within the daily cap; back off on 429 responses and use the updatedMin parameter on list calls to avoid full re-syncs.

### How do I add a task through Jentic?

Search Jentic for 'add a task to google tasks', load the schema for POST /tasks/v1/lists/{tasklist}/tasks, and execute it with the target tasklist ID (use '@default' for the user's primary list) plus the task title and optional due date. Get started with Jentic One, the self-hosted execution layer.

### Is the Google Tasks API free?

Yes, the Google Tasks API is free to use within the standard daily quota. There is no per-call charge - it is part of the Google Workspace and consumer Google account surface, billed only as part of standard Workspace subscriptions where applicable.

### Can I clear completed tasks in bulk?

Yes. POST /tasks/v1/lists/{tasklist}/clear deletes every task in the specified list whose status is 'completed' in a single call. This is the most efficient way to archive finished work; cleared tasks are not recoverable through the API so confirm intent before calling.

### Can I limit what my agent is allowed to do with the Google Tasks API?

Yes. Because you run Jentic One yourself, your own rules decide which Google Tasks operations and credentials the agent may use. Since the task list lives in the URL path (/tasks/v1/lists/{tasklist}/tasks), you can pin the agent to a single list so it only reads and inserts tasks there. You choose the operations it can call, so destructive ones like clearing completed tasks or deleting a list are excluded unless you add them.