Data Sources

Status: Draft Last Updated: 2026-06-15 Audience: customer

This is the per-source reference: what data each source provides, what the end user experiences when authorizing it, how long until data is available, and whether it keeps syncing or is a one-time import. The source identifier strings here are the values you use everywhere else — in the sources parameter of /authorize, in filter: { platforms: [...] } and the platform field of data queries, and in the source field of grants and webhook events.

All example values are synthetic.

Overview

Source	Identifier	Data types	Authorization method	Ongoing sync
Gmail	gmail	Messages, threads	Google OAuth	Yes
Google Contacts	google_contacts	People, identities	Google OAuth	Yes
Google Calendar	google_calendar	Events, participants	Google OAuth	Yes
iMessage	imessage	Messages, conversations	macOS agent	Yes (continuous)
Apple Contacts	apple_contacts	People, identities	macOS agent	Yes (continuous)
Android SMS	android_sms	SMS/MMS messages, threads	Google Data Portability	No (one-time)
Local Files	local-files	Documents	Browser upload	No (one-time)

Identifier spelling. Every identifier uses underscores except local-files, which uses a hyphen. Copy these strings exactly — they are case- and separator-sensitive.

Which sources your end users see on the consent page is controlled by the sources your account is configured to offer; users only ever see and authorize sources in that set. See Authorization Flow for how the consent page presents them.

Google sources (OAuth)

gmail, google_contacts, and google_calendar all authorize the same way: the end user is taken to Google’s standard OAuth consent screen and grants access there. Authorization completes entirely in the browser, and data is typically available within minutes. All three keep syncing — new mail, contacts, and events flow in on an ongoing basis after the initial import.

Gmail — gmail

• Data: email messages and the threads (conversations) they belong to. Queryable as messages (filter platforms: ["gmail"]) and conversations.
• End-user experience: Google OAuth consent in-browser.
• Time to data: minutes after authorization.
• Sync: ongoing.

Google Contacts — google_contacts

• Data: the user’s contacts as people and their platform identities (email addresses, phone numbers). Queryable as persons.
• End-user experience: Google OAuth consent in-browser.
• Time to data: minutes.
• Sync: ongoing.

Google Calendar — google_calendar

• Data: calendar events with timing and participants. Queryable as events, and interleaved into timeline.
• End-user experience: Google OAuth consent in-browser.
• Time to data: minutes.
• Sync: ongoing.

macOS sources (device agent)

imessage and apple_contacts are read from the user’s Mac by the macOS sync agent — a small app the user installs. Both sources are handled by the same agent, so a single installation covers both.

• End-user experience: the user downloads and installs the agent (a .dmg), grants it Full Disk Access in System Settings, and the agent completes authorization (often via a deep link that opens the agent and ties it to the authorization session).
• Time to data: because the agent’s first sync runs on the user’s machine, data can land minutes to hours after authorization — not the moment the user finishes the flow. Use webhooks (sync.initial_completed) to know when the first sync is done rather than assuming data exists immediately.
• Sync: continuous while the agent is installed and running.
• Caveat: macOS only. The user must keep the agent installed for sync to continue.

iMessage — imessage

• Data: iMessage/SMS messages and their conversations. Queryable as messages (filter platforms: ["imessage"]) and conversations.

Apple Contacts — apple_contacts

• Data: the macOS address book as people and identities. Queryable as persons. Bundled with the same agent as iMessage.

Android SMS — android_sms

android_sms uses Google’s Data Portability export rather than a live connection.

• Data: SMS and MMS messages and their threads. Queryable as messages (filter platforms: ["android_sms"]).
• End-user experience: the user runs Google’s Data Portability export on their Android device and authorizes the transfer.
• Time to data: Google processes the export asynchronously — data typically becomes available after roughly 24 hours.
• Sync: one-time, historical. This is a snapshot export, not a live feed; there is no ongoing sync. To refresh, the user runs the export again.
• Caveat: android_sms must be requested in its own /authorize round — it cannot be bundled with other sources in the same sources list. See Authorization Flow.

Local Files — local-files

local-files lets the user contribute documents directly.

• Data: documents (PDFs and text files). Queryable as documents.
• End-user experience: the user selects files or folders through a browser file picker; the upload completes in-session.
• Time to data: minutes after upload completes.
• Sync: one-time per upload — uploaded files are imported once. To add more, the user uploads again.

How identifiers are used downstream

The identifier strings in the table above are the single vocabulary used across every surface:

• Requesting a source: sources=gmail,imessage in the /authorize URL.
• Filtering data: filter: { platforms: ["gmail"] } in data queries; the matching platform field on each result node.
• Checking grants: the source field of the grants query and the management API’s activeGrants.
• Webhook events: the source field of every webhook delivery.

Treat these strings as a stable enumeration. New sources may be added over time; handle an unfamiliar identifier gracefully rather than assuming the set is fixed.

Related Documents

• Authorization Flow — How each source is requested and the per-source consent handoff.
• Data API — Querying each source’s data and filtering by platforms.
• Management API — Per-source grant and sync state across your account.
• Webhooks — Knowing when an asynchronous first import (macOS agent, Android SMS) completes.
• Quickstart — Where source selection first appears in the onboarding walkthrough.