> ## Documentation Index
> Fetch the complete documentation index at: https://the-early-spring18.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Core Concepts: Key Terms and How the Google Platform Works
> Understand the fundamental building blocks of Google — search, data objects, users, API keys, webhooks, and integrations — and how they fit together.
Before you dive into building with Google, it's worth taking a few minutes to understand the key abstractions the platform is built on. Each concept in this guide maps directly to something you'll encounter in the dashboard or the API — and once you understand how they relate to one another, the rest of the documentation will make much more sense. This page is reference material you can return to whenever you need a refresher on terminology or behavior.
Here's the relationship that ties everything together: **users** own **accounts** → accounts contain **data objects** → **API keys** grant programmatic access to those data objects, scoped to exactly the permissions you define. Webhooks and integrations build on top of this foundation to extend what you can do with your data.
***
## Search
Search is the primary way you and your applications retrieve information stored in Google. Every data object you create is indexed automatically — you don't need to configure anything for search to work.
Google supports two complementary query modes:
Full-text search scans the `title` and `content` fields of every data object in your account and returns results ranked by **relevance score** — a float between `0.0` and `1.0` that reflects how closely a result matches your query. Higher scores appear first.
```bash theme={null}
# Search for "quarterly report" across all data objects
curl 'https://api.google.com/v1/search?q=quarterly+report' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
Full-text search is case-insensitive and handles common linguistic variations (for example, "running" matches "run"). Stop words like "the" and "and" are ignored to improve result quality.
Structured search lets you filter results by metadata fields using a simple query syntax. You can combine filters with full-text queries or use them independently.
```bash theme={null}
# Find all data objects where metadata.status equals "published"
curl 'https://api.google.com/v1/search?filter=metadata.status:published' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
Supported filter operators include `:` (equals), `>` and `<` (numeric comparison), and `!=` (not equals). Multiple filters can be combined with `AND` and `OR` logic.
You can combine full-text and structured search in a single request by including both a `q` parameter and a `filter` parameter. For example: `?q=annual+report&filter=metadata.year:2024`.
***
## Data Objects
Data objects are the core unit of storage in Google. Every piece of information you save to the platform — a document, a record, a note, a structured entry — is represented as a data object with a consistent set of fields.
| Field | Type | Description |
| ------------ | -------- | ----------------------------------------------------------------------------------------------- |
| `id` | `string` | A unique, platform-generated identifier (e.g., `obj_4x7kLm`). Immutable after creation. |
| `title` | `string` | A short, human-readable label for the object. Indexed for full-text search. |
| `content` | `string` | The main body of the object. Supports plain text or Markdown. Indexed for full-text search. |
| `metadata` | `object` | An open-ended key-value map for any additional structured data you want to store and filter on. |
| `created_at` | `string` | ISO 8601 timestamp of when the object was created. |
| `updated_at` | `string` | ISO 8601 timestamp of the most recent update. |
```bash theme={null}
curl -X POST https://api.google.com/v1/data \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"title": "Q4 Strategy Brief",
"content": "This document outlines our strategy for Q4...",
"metadata": { "department": "marketing", "year": 2024, "status": "draft" }
}'
```
A successful response returns the full object including its system-assigned `id`, `created_at`, and `updated_at` timestamps.
To update an existing data object, send a `POST` request to `/v1/data` and include the object's `id` along with the fields you want to change. Fields you omit are left untouched. To update nested metadata keys selectively, use dot notation in your payload (e.g., `"metadata.status": "published"`).
There is no enforced schema for the `metadata` field — you decide what keys and value types make sense for your use case. However, for structured search filters to work reliably, it's good practice to use consistent key names and value types across objects of the same logical type.
***
## Users & Accounts
Every person who interacts with Google does so through a **user** identity tied to a verified email address. A user can belong to one or more **accounts** — the organizational container that holds data objects, API keys, integrations, and billing information.
### Roles
Within a multi-seat account, each user is assigned one of three roles:
Full control over the account, including billing, deleting the account, and transferring ownership. Each account has exactly one owner at a time.
Can manage team members, generate and revoke API keys, configure integrations, and perform all data operations. Cannot access billing or delete the account.
Can create, read, update, and delete data objects and run searches. Cannot manage team members, API keys, or integrations unless explicitly granted additional permissions.
Role-based access control applies to dashboard access only. API key scopes (described in the next section) independently govern what each programmatic client can do — a member-role user can generate a key with admin-level write scope if their account settings allow it.
***
## API Keys
API keys are the credentials you use to authenticate requests to the Google REST API. Every key belongs to an account and carries one or more **scopes** that define exactly what the key is allowed to do.
### Scopes
| Scope | What It Allows |
| ------- | ----------------------------------------------------------------------------------- |
| `read` | Search data objects and retrieve their contents. No write operations permitted. |
| `write` | Create, update, and delete data objects. Includes all `read` capabilities. |
| `admin` | Manage API keys, team members, and integrations. Includes all `write` capabilities. |
Treat API keys like passwords. Never expose them in client-side code, public repositories, or unencrypted logs. Use environment variables or a secrets manager to inject keys into your applications at runtime. If a key is ever compromised, revoke it immediately from **Settings → API Keys** and generate a replacement.
### Key Lifecycle
Create a new key in **Settings → API Keys → New Key**. Assign a name and scope, then copy the key value — it is shown only once.
Include the key in the `Authorization` header of every API request as a Bearer token: `Authorization: Bearer YOUR_API_KEY`.
Periodically generate a new key and update your integrations before revoking the old one. Regular rotation reduces the blast radius of any accidental exposure.
Delete a key from the **API Keys** settings page when it's no longer needed or if you suspect it has been compromised. Revocation is immediate and permanent.
***
## Webhooks
Webhooks allow Google to push real-time notifications to your server the moment something changes in your account. Instead of polling the API repeatedly, you register a URL and Google delivers an HTTP `POST` payload to that endpoint whenever a subscribed event fires.
### Supported Events
| Event | Triggered When |
| -------------- | ------------------------------------------------------------------------ |
| `data.created` | A new data object is successfully created in your account. |
| `data.updated` | An existing data object's `title`, `content`, or `metadata` is modified. |
| `data.deleted` | A data object is permanently deleted from your account. |
| `user.created` | A new user is added to your account (e.g., accepts a team invitation). |
### Example Webhook Payload
```json theme={null}
{
"event": "data.created",
"timestamp": "2024-11-15T09:32:10Z",
"account_id": "acc_9z3qRt",
"data": {
"id": "obj_4x7kLm",
"title": "Q4 Strategy Brief",
"created_at": "2024-11-15T09:32:09Z"
}
}
```
Always validate incoming webhook payloads using the HMAC signature Google includes in the `X-Google-Signature` header. This confirms the request genuinely originated from Google and hasn't been tampered with in transit.
***
## Integrations
Integrations connect Google to external tools and services, enabling automatic data synchronization and cross-platform workflows without custom middleware. You can set up integrations from **Settings → Integrations** in your dashboard.
Google supports two connection methods:
OAuth integrations let you authorize Google to read from or write to a third-party service on your behalf, without sharing passwords. You'll be redirected to the service's authorization page, grant the requested permissions, and be returned to Google automatically. The connection is revocable at any time from either platform.
OAuth is the recommended method for services that support it because credentials are never stored by Google — only a scoped access token that can be revoked independently.
For services that don't support OAuth, you can connect by entering the third-party service's API key directly into Google's integration settings. Google stores the key encrypted at rest and uses it only to make authorized requests on your behalf.
When using API key integrations, make sure you generate a dedicated key in the third-party service specifically for Google — don't reuse a key that's also used by other applications. This way you can revoke Google's access independently if needed.
When an integration runs — either on a schedule or triggered by a webhook event — Google pulls the relevant data from the external service and represents it as data objects in your account. These objects are fully searchable, can be referenced via the API, and will fire `data.created` or `data.updated` webhook events if you have listeners configured for those events.
Yes. If the service you want to connect doesn't have a built-in integration, you can build your own using the Google REST API and webhooks. Your custom integration can listen for Google webhook events and push changes to the external service, and can also poll or subscribe to the external service and write updates back to Google using the API.