canonical: https://jentic.com/apis/googleapis.com/alertcenter # Google Workspace Alert Center API The Google Workspace Alert Center API exposes alerts about issues affecting a Workspace domain - phishing campaigns, suspicious account activity, malware, account compromise, and policy violations - that Google's security systems flag. It supports listing, retrieving, undeleting, and batch-deleting alerts, attaching analyst feedback, and reading per-alert metadata. It is intended for security teams that want Workspace alerts pulled into their SIEM or SOAR rather than triaged in the Alert Center web UI. ## For AI agents List, fetch, and triage Google Workspace security alerts (phishing, malware, suspicious sign-ins) across a customer domain. ## Scope Does not handle Workspace user provisioning, admin audit logs, or detection rule configuration - use for reading and triaging Workspace security alerts only. ## Capabilities - List Workspace security alerts filtered by type, source, and time range - Retrieve the full payload of a single alert including the affected users and Google's analysis - Attach analyst feedback (NOT_USEFUL, SOMEWHAT_USEFUL, VERY_USEFUL) to an alert for tuning - Batch-delete or batch-undelete alerts to clear or restore noisy detections - Read per-alert metadata to track triage status across the security team - Update domain-level Alert Center settings such as notification recipients ## Use cases ### Workspace Alerts in a SIEM Security teams want every Workspace security alert (phishing, suspicious sign-in, malware) to land in their SIEM alongside endpoint and identity alerts. The Alert Center API is the only programmatic surface for these - they cannot be pulled from the audit log alone. A poller lists new alerts, GETs each by ID, and forwards the structured payload to the SIEM. The 11 endpoints cover list, get, feedback, metadata, undelete, batchDelete and batchUndelete. Example prompt: GET /v1beta1/alerts with a filter on createTime greater than the last watermark, then GET /v1beta1/alerts/{alertId} for each new ID and ship the result as a SIEM event. ### Analyst Feedback Loop Security operations teams want to tell Google which Workspace alerts were useful so detections improve over time. The createFeedback endpoint attaches a feedback rating to an alert. Combined with metadata reads, this lets a SOAR playbook record a triage decision and submit feedback in the same step rather than asking analysts to leave the SIEM and click in the Alert Center UI. Example prompt: After an analyst dispositions an alert in the SOAR, POST to /v1beta1/alerts/{alertId}/feedback with type=VERY_USEFUL or NOT_USEFUL and an email of the submitting analyst. ### Bulk Alert Cleanup When a misconfigured rule fires hundreds of false-positive alerts, security teams need a fast way to clear them and a safe way to restore them if needed. batchDelete soft-deletes a list of alert IDs and batchUndelete restores them. This avoids hand-clicking through pages of Alert Center entries when a noisy detection misfires. Example prompt: POST /v1beta1/alerts:batchDelete with the list of alertIds for the misfiring detection, and on confirmation that the rule was wrong call /v1beta1/alerts:batchUndelete with the same list. ### Agent-Triaged Workspace Alerts An agent integrating Alert Center via Jentic can search for the listing operation, fetch each alert, summarise it with a language model, and post a triage suggestion to chat. Jentic isolates the Workspace OAuth credential and exposes only the alert payload schema, so the workflow runs without a custom OAuth implementation. Setup time drops from a couple of days to under an hour. Example prompt: Use the Jentic search query 'list Google Workspace security alerts' to discover the operation, then list new alerts, fetch each by ID, summarise the data block, and post a structured triage card to Slack. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /v1beta1/alerts | List alerts for a Workspace customer with optional filter and orderBy | | GET | /v1beta1/alerts/{alertId} | Get a single alert by ID | | POST | /v1beta1/alerts/{alertId}/feedback | Attach analyst feedback to an alert | | GET | /v1beta1/alerts/{alertId}/metadata | Get triage metadata for an alert | | POST | /v1beta1/alerts:batchDelete | Soft-delete a batch of alerts | | POST | /v1beta1/alerts:batchUndelete | Restore a previously deleted batch of alerts | ## Key resources - **Alerts** — List, get, batch-delete, and batch-undelete Workspace security alerts - **Alert Feedback** — Attach analyst feedback ratings to specific alerts - **Alert Metadata** — Per-alert metadata describing assignee and triage state - **Settings** — Domain-level Alert Center notification settings ## Why Jentic - **Setup:** Wiring the Google Workspace Alert Center API by hand means setting up Google OAuth 2.0 via a domain-wide delegated service account, minting short-lived access tokens, and pointing calls at the alertcenter.googleapis.com host. Through Jentic you install once, import the Alert Center API from the API Directory, store the OAuth credential once, and your agent calls it. - **Permission scoping:** Alert Center puts the alert id in the URL path (/v1beta1/alerts/{alertId}), so a rule can pin your agent to reading a specific alert and its metadata. You choose the operations it may call, so state-changing actions like posting feedback or batchDelete are not included unless you add them. - **Credential handling:** Your Google service account credential is stored once, encrypted, by your own Jentic One instance and exchanged for short-lived access tokens at execution time. The key never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list Google Workspace security alerts' or 'read alert metadata', and Jentic returns the matching Alert Center operation with its filter and pagination schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Admin SDK API** — Admin SDK provides user, group, and audit log data that enriches Alert Center alerts. - **Advisory Notifications API** — Advisory Notifications carries broader Google-issued advisories; Alert Center carries Workspace security alerts. - **Cloud DLP API** — Cloud DLP scans and redacts sensitive data across Google Cloud sources; Alert Center is the narrow feed of Workspace-originated security alerts. ## FAQ ### What authentication does the Alert Center API use? OAuth 2.0 with the apps.alerts scope, typically via a Workspace domain-wide delegated service account so the API can read alerts for the customer. Jentic stores the service account JSON in its encrypted vault and minted access tokens are short-lived, so secrets never enter agent context. ### Can I forward every Workspace phishing alert into my SIEM? Yes. Call /v1beta1/alerts with a filter such as type="Phishing message detected post-delivery" AND createTime>="...", then GET /v1beta1/alerts/{alertId} for each result and post the payload as a SIEM event. ### What are the rate limits for the Alert Center API? Alert Center is governed by the standard Google Workspace API per-project quota. Default quota covers normal SIEM polling intervals; high-frequency polling may need a quota increase via the Google Cloud Console quotas page for the Alert Center API. ### How do I submit analyst feedback on an alert through Jentic? Search Jentic for 'submit feedback on a Google Workspace alert', load the schema for /v1beta1/alerts/{alertId}/feedback, and POST with type and email. Run pip install jentic and the async search, load, execute pattern. ### Does the Alert Center API let me change which alerts Google generates? No. The detection rules are owned by Google. The API lets you list alerts, attach feedback, manage triage state, and update domain-level notification settings, but it does not configure detection logic itself. ### Why is this API marked v1beta1? Google has shipped Alert Center as v1beta1 for an extended period and treats it as production-grade for Workspace customers. The endpoint paths in this enrichment reflect the v1beta1 paths the API actually exposes. ### Can I limit what my agent is allowed to do with the Google Workspace Alert Center API? Yes. Because you run Jentic One self-hosted, your own rules decide which Alert Center operations and credentials the agent may use. You can pin the agent to read-only calls like GET /v1beta1/alerts and GET /v1beta1/alerts/{alertId}/metadata, and because the alert id sits in the URL path you can scope it to a specific alert. State-changing operations such as POST feedback or alerts:batchDelete stay off limits unless you explicitly add them.