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

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.

# 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

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.

# 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.

Creating a Data Object via the API

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.

Updating a Data Object

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:

Owner

Full control over the account, including billing, deleting the account, and transferring ownership. Each account has exactly one owner at a time.

Admin

Can manage team members, generate and revoke API keys, configure integrations, and perform all data operations. Cannot access billing or delete the account.

Member

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

1. Generate

   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.

2. Use

   Include the key in the Authorization header of every API request as a Bearer token: Authorization: Bearer YOUR_API_KEY.

3. Rotate

   Periodically generate a new key and update your integrations before revoking the old one. Regular rotation reduces the blast radius of any accidental exposure.

4. Revoke

   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

{
  "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

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.

API Key

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.

What happens when an integration syncs data?

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.

Can I build a custom integration?

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.