---
name: workspace-api-integrations
description: "Umbrella for workspace/productivity APIs and CLIs: Google Workspace, Airtable, Notion, email via Himalaya, and map/geocoding utilities."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [productivity, google-workspace, airtable, notion, email, maps, api, automation]
---

# Workspace API Integrations

Use when the user asks to operate external productivity/workspace systems: Gmail/Calendar/Drive/Docs/Sheets, Airtable bases, Notion pages/databases, IMAP/SMTP email, geocoding/POI/routes/timezones, or similar API-backed workspace actions.

## Triage

- **Google Workspace**: Gmail, Calendar, Drive, Docs, Sheets, Contacts; prefer the configured `gws`/`gog` CLI/Python helpers when present. For private Drive retrieval with `gog`, keyring env handling, and download locations, use `references/gog-drive-private-documents.md`. When a user says a file was uploaded but it is not visible, use `references/drive-missing-upload-triage.md` before giving up: list the expected parent/subfolder, search exact name/name fragments/MIME/date windows, retry once for indexing lag, then report checked locations precisely. When the user uploads a ZIP to Drive and asks to unpack/analyze it in place, use `references/google-drive-zip-unpack-and-briefing.md` for the locate→download→validate→extract→upload→OCR/briefing workflow. When importing an entire Drive project/app folder into local storage or Git, use `references/google-drive-folder-to-local-project-import.md` to recursively download while skipping virtualenvs/caches and preserving a clean source cache. When updating an existing Drive file that the user will keep editing, prefer `gog drive upload <localPath> --replace <file_id> --name <same-name>` so the existing file/link/permissions are preserved; verify with `drive get` and folder `ls` to avoid duplicates.
- **Dropbox Transfer → Google Drive**: when a Dropbox Transfer link must be saved locally and uploaded to Drive, use the browser to trigger the dynamic ZIP download, then recreate the folder tree with `gog`; see `references/dropbox-transfer-to-google-drive.md`.
- **Airtable**: records, bases, tables, filters, CRUD, and upserts via REST API.
- **Notion**: pages, databases, markdown conversion, and `ntn`/REST workflows.
- **Email / Himalaya**: IMAP/SMTP actions from the terminal; inspect before sending and avoid leaking secrets.
- **Maps/geocoding**: OpenStreetMap/Nominatim/OSRM/timezone-style lookups and route calculations.

## Workflow

1. Identify the target account/workspace/base/database/mailbox and required credentials.
2. Use read/list/search calls before mutating external systems.
3. For writes, construct a minimal payload, execute once, then verify by reading back the created/updated object.
4. Return stable handles: URLs, IDs, record keys, message IDs, or coordinates.
5. Keep rate limits, privacy, and user-visible side effects explicit.

## Preserved source packages

Copied under `references/absorbed-packages/`: `google-workspace`, `airtable`, `notion`, `himalaya`, and `maps`.