Tasks API

Manage task lists and tasks

Overview

The Google Tasks API allows you to manage task lists and individual tasks programmatically.

API Name: tasks
Version: v1
Official Documentation: Tasks API Reference

Common Resources

Task Lists

Manage task lists (containers for tasks).

tasklist · string · required

The task list ID or @default for the default list

title · string

The task list title

Tasks

Manage individual tasks.

tasklist · string · required

The task list ID

task · string

The task ID

title · string

The task title

due · string

Due date (RFC 3339 timestamp)

Common Methods

List Task Lists

gws tasks tasklists list

items · array

Array of task list objects

id · string

The task list ID

title · string

The task list title

updated · string

Last modification time

Get Task List

gws tasks tasklists get --params '{
  "tasklist": "@default"
}'

Create Task List

gws tasks tasklists insert --json '{
  "title": "Work Tasks"
}'

List Tasks

gws tasks tasks list --params '{
  "tasklist": "@default",
  "showCompleted": false
}'

items · array

Array of task objects

id · string

The task ID

title · string

The task title

status · string

Task status: needsAction or completed

due · string

Due date (RFC 3339 timestamp)

Create Task

gws tasks tasks insert \
  --params '{"tasklist": "@default"}' \
  --json '{
    "title": "Review pull request",
    "notes": "Check PR #123 for the API changes",
    "due": "2026-03-10T00:00:00.000Z"
  }'

Get Task

gws tasks tasks get --params '{
  "tasklist": "@default",
  "task": "task123"
}'

Update Task

gws tasks tasks update \
  --params '{"tasklist": "@default", "task": "task123"}' \
  --json '{
    "title": "Updated task title",
    "status": "completed"
  }'

Delete Task

gws tasks tasks delete --params '{
  "tasklist": "@default",
  "task": "task123"
}'

Task Operations

Mark task complete

gws tasks tasks update \
  --params '{"tasklist": "@default", "task": "task123"}' \
  --json '{"status": "completed"}'

Response Format

Task list response:

{
  "items": [
    {
      "id": "MDAxNjM4NTQ2NzY4NTQ2NzY4NTQ",
      "title": "My Tasks",
      "updated": "2026-03-05T10:30:00.000Z",
      "selfLink": "https://www.googleapis.com/tasks/v1/users/@me/lists/MDAxNjM4NTQ2NzY4NTQ2NzY4NTQ"
    }
  ]
}

Task response:

{
  "id": "task123",
  "title": "Review pull request",
  "notes": "Check PR #123 for the API changes",
  "status": "needsAction",
  "due": "2026-03-10T00:00:00.000Z",
  "updated": "2026-03-05T14:20:00.000Z",
  "selfLink": "https://www.googleapis.com/tasks/v1/lists/@default/tasks/task123"
}

Key Resources

• tasklists - Manage task lists
• tasks - Manage tasks within lists

Task Hierarchy

Tasks can be organized hierarchically with parent-child relationships:

# Create parent task
gws tasks tasks insert \
  --params '{"tasklist": "@default"}' \
  --json '{"title": "Project Launch"}'

# Create subtask
gws tasks tasks insert \
  --params '{"tasklist": "@default", "parent": "parentTaskId"}' \
  --json '{"title": "Write documentation"}'

Filtering Tasks

# Show only incomplete tasks
gws tasks tasks list --params '{
  "tasklist": "@default",
  "showCompleted": false
}'

# Show tasks updated after a date
gws tasks tasks list --params '{
  "tasklist": "@default",
  "updatedMin": "2026-03-01T00:00:00.000Z"
}'

# Show tasks due before a date
gws tasks tasks list --params '{
  "tasklist": "@default",
  "dueMax": "2026-03-31T23:59:59.000Z"
}'

Learn More

• Tasks API Guide
• Managing tasks
• Task lists

Schema Inspection

Before calling any method, inspect its schema:

gws schema tasks.tasklists.list
gws schema tasks.tasks.insert