gw-api

Generic Google API Invoker

Invocation

CLI="python3 ${CLAUDE_PLUGIN_ROOT}/cli/gw.py"

When to Use

• Prefer the curated groups (gmail, calendar, sheets, docs, tasks, forms) for anything they cover — they have task-shaped flags and validated response shapes.
• Use gw api for everything else: services without a curated group, or curated services' methods the groups don't expose.
• SERVICE is an alias (gw api list shows all 18) or the api:version escape hatch for any Google API, e.g. admin:directory_v1.

Workflow: schema → dry-run → call

Always resolve the method shape before calling:

# 1. Find the service and browse its surface
$CLI api list --compact
$CLI api describe gmail --compact                    # top-level resources
$CLI api describe gmail users.messages --compact     # methods on a resource

# 2. Inspect the method: params, required scopes, request/response schema
$CLI schema gmail.users.messages.list --compact

# 3. Validate the call without executing (offline, no auth needed)
$CLI api call gmail users.messages.list --params '{"userId":"me","maxResults":5}' --dry-run

# 4. Execute
$CLI api call gmail users.messages.list --params '{"userId":"me","maxResults":5}' --compact

--dry-run prints {service, method, httpMethod, uri_template, params, body, required_scopes, destructive} and catches unknown/missing-required params before any network call.

The discovery document is the contract, not the published examples

A vendor's documentation shows what usually works. The discovery document defines what is guaranteed. When they disagree, the published example is the one that can change.

This matters most for enums, which are the cheapest thing to get wrong and the hardest to debug, because a rejected enum reports as a generic 400 rather than as "that value is not in the list". Fetch the document and read the enum yourself:

# Any Google API, no auth, no gw needed
curl -s "https://<api>.googleapis.com/\$discovery/rest?version=<version>" -o /tmp/d.json

# The enum for one request field
python3 -c "import json;d=json.load(open('/tmp/d.json'));print(d['schemas']['<RequestSchema>']['properties']['<field>']['enum'])"