HES gTasks — Docs

Multi-tenant Google Tasks proxy with an HTTP API, MCP connector for Claude Code, recurring tasks, and per-key list ACL.

Quick start

1. 1. Sign in with Google at /login/.
2. 2. Create an API key at /api-keys/ — pick Full access or Selected lists with read/write toggles.
3. 3. Use the key in an X-API-Key header on every call.

Authentication

Every endpoint requires an API key sent in one of two ways:

X-API-Key: hes_AbCdEf...
   — or —
Authorization: Bearer hes_AbCdEf...

Keys begin with hes_. The raw key is shown once at creation time; we store only a SHA-256 hash thereafter.

Errors

All errors return JSON in DRF's default shape:

{"detail": "Human-readable explanation"}

Resources

TaskList

{
  "kind": "tasks#taskList",
  "id":   "MDczMjMxOTYx...",     // string, opaque, Google-issued
  "etag": "\"PHgZba4TDTE\"",
  "title": "My Tasks",            // string, the displayed name
  "updated": "2026-05-13T16:50:01.366Z",
  "selfLink": "https://www.googleapis.com/tasks/v1/users/@me/lists/..."
}

Task

{
  "kind": "tasks#task",
  "id":   "RmNVR29aOEp4...",      // string, opaque
  "etag": "\"abc123\"",
  "title": "Buy milk",            // string, required for create
  "status": "needsAction",        // "needsAction" | "completed"
  "due":   "2026-06-01T00:00:00.000Z",  // RFC3339, date-only (time portion ignored by Google)
  "notes": "2% organic",          // string, optional
  "completed": "2026-06-02T14:00:00Z",  // RFC3339, only set when status="completed"
  "parent": "AbCdEf...",          // present if this is a subtask
  "position": "00000000003221225472",
  "updated": "2026-05-13T16:00:00Z",
  "hidden": false,
  "deleted": false,
  "links": [{ "type": "email", "description": "...", "link": "https://..." }],
  "selfLink": "..."
}

Endpoints

Base URL: http://gtasks.henry.enterprises/api/v1

Task lists

[
  {
    "kind": "tasks#taskList",
    "id": "MDczMjMxOTYxNjAxMDc5MzI3NTc6MDow",
    "title": "My Tasks",
    "updated": "2026-05-10T16:49:31.366Z",
    "etag": "...", "selfLink": "..."
  },
  ...
]

{ "title": "Groceries" }

{
  "kind": "tasks#taskList",
  "id": "AbCdEf...",
  "title": "Groceries",
  "updated": "2026-05-13T17:00:00.000Z",
  "selfLink": "..."
}

{ "kind": "tasks#taskList", "id": "...", "title": "My Tasks", ... }

{ "title": "Renamed list" }

{ "kind": "tasks#taskList", "id": "...", "title": "Renamed list", ... }

Tasks

[
  {
    "kind": "tasks#task",
    "id": "RmNVR29aOEp4dUtNWXg2Ug",
    "title": "Checkout Rust Skins",
    "status": "needsAction",
    "due": "2026-05-07T00:00:00.000Z",
    "notes": "https://store.steampowered.com/...",
    "position": "00000000003221225472",
    "updated": "2026-05-07T06:04:38.354Z"
  },
  ...
]

{
  "title": "Buy milk",                           // required
  "notes": "2% organic",                         // optional
  "due":   "2026-06-01T00:00:00.000Z",           // optional, RFC3339
  "status": "needsAction"                        // optional, default "needsAction"
}

{
  "kind": "tasks#task",
  "id": "NewTaskAbCdEf...",
  "title": "Buy milk",
  "status": "needsAction",
  "due": "2026-06-01T00:00:00.000Z",
  "notes": "2% organic",
  "position": "00000000004294967296",
  "updated": "2026-05-13T17:00:00.000Z"
}

{ "kind": "tasks#task", "id": "...", "title": "...", ... }

{
  "title":  "Updated title",
  "notes":  "New notes",
  "due":    "2026-07-01T00:00:00.000Z",
  "status": "completed"           // setting "completed" auto-fills the completed timestamp
}

{ "kind": "tasks#task", ...updated task... }

{
  "parent":   "AnotherTaskId",  // null/omit = top level
  "previous": "TaskBeforeId"    // null/omit = first in list
}

{ "kind": "tasks#task", "id": "...", "position": "new-position", ... }

End-to-end example

# 1. List your task lists
curl -s -H "X-API-Key: hes_..." \
  http://gtasks.henry.enterprises/api/v1/tasklists/

# 2. Create a task in the first list
LIST_ID=MDczMjMxOTYx...
curl -s -X POST \
  -H "X-API-Key: hes_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Buy milk", "due": "2026-06-01T00:00:00.000Z"}' \
  http://gtasks.henry.enterprises/api/v1/tasklists/$LIST_ID/tasks/

# 3. Mark it completed
TASK_ID=NewTaskAbC...
curl -s -X PATCH \
  -H "X-API-Key: hes_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}' \
  http://gtasks.henry.enterprises/api/v1/tasklists/$LIST_ID/tasks/$TASK_ID/

# 4. Delete it
curl -s -X DELETE \
  -H "X-API-Key: hes_..." \
  http://gtasks.henry.enterprises/api/v1/tasklists/$LIST_ID/tasks/$TASK_ID/

Rate limits

60 requests per minute per API key. Exceeding returns 429 Too Many Requests with a Retry-After hint in seconds.

Per-key list ACL

When you create an API key on the API Keys page, choose:

• Full access — read/write across every list you own; can also create new top-level lists.
• Selected lists — per-list Read and Write toggles. Write implies Read.

Scoped keys can only see the lists they were granted; GET /tasklists/ is filtered server-side. Writes to ungranted lists return 403. Scoped keys cannot create new top-level lists.

Recurring tasks

Google's public Tasks API has no recurrence field, so we own it locally. From a task's detail modal in the web UI, pick Repeat and choose Daily/Weekly/Monthly/Yearly with an interval. Two trigger modes:

• After completing — next instance spawns when you mark the current one complete.
• On a schedule — a background worker polls every 10 min and spawns due instances regardless of completion state.

Recurrence configuration is currently only exposed via the web UI (not the REST API). Tracking the issue.

Claude Code MCP connector

A Python MCP server is bundled in hes-gtasks/mcp/:

pip install -r mcp/requirements.txt

claude mcp add gtasks python /path/to/hes-gtasks/mcp/server.py \
  --env GTASKS_API_URL=http://gtasks.henry.enterprises/api/v1 \
  --env GTASKS_API_KEY=hes_...

Tools exposed (each maps 1:1 to a REST endpoint above): list_tasklists, get_tasklist, create_tasklist, update_tasklist, delete_tasklist, list_tasks, get_task, create_task, update_task, delete_task, move_task, clear_completed.

All ACL rules apply automatically: a scoped key only exposes accessible lists to the AI agent.

OAuth scopes we request from you

• https://www.googleapis.com/auth/tasks — read/write Google Tasks
• openid
• https://www.googleapis.com/auth/userinfo.email
• https://www.googleapis.com/auth/userinfo.profile

Refresh tokens are stored encrypted at rest (Fernet AES-128). API keys are stored as SHA-256 hashes; the raw value is shown once at creation.