canonical: https://jentic.com/apis/googleapis.com/vault

# Google Vault API

The Google Vault API provides programmatic retention and eDiscovery for Google Workspace data including Gmail, Drive, Chat, Meet, Voice, and Groups. It lets compliance teams create matters, place legal holds on accounts and organizational units, run searches across a domain, and export the resulting evidence for review. Access requires Vault privileges and matter-level sharing, and every export, hold, and search action is auditable.

## For AI agents

Manage legal matters, holds, searches, and exports across Google Workspace so an agent can automate eDiscovery and retention workflows without manual console clicks.

## Scope

Does not handle live mailbox automation, file editing, or user provisioning - use for eDiscovery matters, holds, searches, and exports across Workspace only.

## Capabilities

- Open and close matters that scope an eDiscovery investigation
- Place legal holds on specific accounts or entire organizational units across Workspace services
- Run domain-wide searches across Gmail, Drive, Chat, Voice, and Groups within a matter
- Export held data with metadata for review in third-party eDiscovery platforms
- Share a matter with collaborating reviewers and revoke access when an investigation closes
- List exports and download them once Vault has finished compiling the archive

## Use cases

### Departing Employee Legal Hold

When an employee departs under disputed circumstances, Workspace administrators automate a legal hold across the user's Gmail, Drive, and Chat data so messages and files cannot be permanently deleted. The Google Vault API creates a matter, attaches a hold scoped to the user account, and reports back when retention is in effect. This replaces a manual console workflow that typically takes a compliance analyst 20-30 minutes per departure.

Example prompt: Create a matter named Departure-Smith, place a hold on user smith@example.com covering MAIL and DRIVE, and confirm the hold is active

### eDiscovery Search and Export

Legal teams responding to a litigation request use the Vault API to scope a search by custodian list, date range, and keyword query, then export the matching messages and files for outside counsel review. The API exposes the full lifecycle: create matter, add accounts to a hold, run a saved query, kick off an export, and poll until the export bundle is ready for download. Exports include metadata required for chain-of-custody documentation.

Example prompt: Create a matter, run a search for emails containing project-falcon between 2026-01-01 and 2026-03-31, and start an MBOX export

### Compliance Audit Reporting

Compliance and security teams enumerate active matters and holds to produce monthly audits showing which custodians are under preservation. The Vault API returns matters paginated by state and exposes hold metadata including affected services, reducing audit prep from a multi-hour manual exercise to a scripted report. Combined with Workspace admin reporting, this gives a single source of truth for regulators.

Example prompt: List every matter in OPEN state, enumerate its holds, and write a CSV of custodian-to-service mappings

### AI Agent Compliance Assistant

An AI agent integrated through Jentic responds to compliance prompts like 'preserve everything from user X for the next 90 days' by discovering the Vault hold operations via intent search, loading the relevant request schemas, and executing them with the right matter and account scope. Because Vault uses OAuth 2.0 with admin scopes, Jentic isolates the consent token in your Jentic One instance so the agent never holds the raw credential.

Example prompt: Search Jentic for create a matter and place a hold, then chain those operations for a named user

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/matters | Create a new eDiscovery matter |
| GET | /v1/matters | List matters filtered by state |
| POST | /v1/matters/{matterId}/holds | Add a hold to a matter |
| GET | /v1/matters/{matterId}/holds | List holds in a matter |
| POST | /v1/matters/{matterId}/exports | Start an export of held data |
| GET | /v1/matters/{matterId}/exports | List exports for a matter |
| POST | /v1/matters/{matterId}/savedQueries | Create a saved search query |

## Key resources

- **Matters** — Container for an investigation; supports create, list, update, undelete, close, reopen, and share operations
- **Holds** — Preservation rules attached to a matter that lock data on accounts or org units across Workspace services
- **Saved Queries** — Reusable search definitions scoped to a matter
- **Exports** — Async jobs that bundle held data into downloadable archives with chain-of-custody metadata

## Why Jentic

- **Setup:** Wiring the Google Vault API by hand means setting up Google OAuth, requesting the ediscovery scope, building the matter, hold, and export path parameters, and refreshing tokens yourself. Through Jentic you install once, import the Google Vault API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** Google Vault puts the matter in the URL path (/v1/matters/{matterId}/holds), so a rule can pin your agent to one matter: it can create holds, exports, and saved queries there and nothing else. You choose the operations it may call, so placing a legal hold or starting an export is not included unless you add it.
- **Credential handling:** Your Google Vault OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'place a hold on a user' or 'create an ediscovery matter', and Jentic returns the matching Vault v1 operation with its input schema, including the corpus enum and accounts array, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Admin SDK API** — Manage the Workspace users and org units that Vault holds and searches operate against
- **Google Drive API** — Access live Drive content; Vault preserves and exports a frozen copy for compliance
- **Sensitive Data Protection (DLP) API** — Classify and redact sensitive data discovered during a Vault export
- **Gmail API** — Direct access to mailbox contents that Vault holds preserve

## FAQ

### What authentication does the Google Vault API use?

The Google Vault API uses OAuth 2.0 with the ediscovery scope family (https://www.googleapis.com/auth/ediscovery and ediscovery.readonly). Through Jentic, the OAuth token is stored encrypted in your Jentic One instance and only a scoped reference is exposed to the agent at execution time.

### Can I place a legal hold on a Workspace user with the Google Vault API?

Yes. Use POST /v1/matters/{matterId}/holds with a corpus of MAIL, DRIVE, GROUPS, HANGOUTS_CHAT, or VOICE and an accounts list. The same endpoint accepts an orgUnit object to hold an entire organizational unit instead of named accounts.

### What are the rate limits for the Google Vault API?

Vault uses standard Workspace per-project quotas with a default of around 1,500 requests per minute per project. Long-running operations like exports do not count against per-minute quotas but are bounded by daily export size limits documented in the Vault admin help center.

### How do I run an eDiscovery export through Jentic with the Google Vault API?

Install Jentic with pip install jentic, search for create vault export, load the schema for POST /v1/matters/{matterId}/exports, then execute with the matter ID, query, and export format (MBOX, PST, or individual files for Drive). Poll GET /v1/matters/{matterId}/exports/{exportId} until status is COMPLETED to retrieve the download URLs.

### Does the Google Vault API support exporting Drive and Chat data, not just Gmail?

Yes. The corpus field on a search or hold accepts MAIL, DRIVE, GROUPS, HANGOUTS_CHAT, and VOICE. Exports return data in service-specific formats - MBOX or PST for mail, individual files plus metadata for Drive, and Chat conversation archives.

### Why does my Vault API call return PERMISSION_DENIED even with a valid token?

Vault enforces matter-level access on top of OAuth scopes. The authenticated account must either own the matter, have it shared, or hold the View All Matters privilege at the Workspace admin level. Share the matter with the service account or grant the privilege in the admin console.

### Can I limit what my agent is allowed to do with the Google Vault API?

Yes. Because you run Jentic One yourself, your own rules decide which Google Vault operations the agent may call, so it can create holds, exports, and saved queries only if you add those operations. Google Vault puts the matter in the URL path (/v1/matters/{matterId}/holds), so you can pin the agent to a single matter and keep it out of every other one. You also hold the OAuth credential, so placing a legal hold or starting an export happens only within the operations and matter scope you granted.