Sources

Google Drive

Connect a Google account and feed a document base from the files you choose. The narrow Drive scope means consent covers those files and nothing else in the account.

Connect a Google account once and feed a document base from files in Drive. The consent screen asks for the narrowest Drive permission Google offers, so your users are not handing over their whole Drive to read a handbook.

How the grant works, and what that means for you

Engram uses the drive.file scope. It is a per-item permission: the app can see only the files a person explicitly hands it through the Google Picker, and nothing else in the account. That is why consent reads "only the files you choose", and it is why there is no Google restricted scope review sitting between you and using this.

Picking a folder does not grant its children. Under drive.file, each picked file is itself the grant. A folder pick can come back with nothing readable inside it, which shows up as an import that adds zero documents. Select the files you want in the Picker, or move them into a folder and pick them there. This is Google's behaviour, not a setting we can change.

1. Connect the account

Connecting is a browser flow, so it happens in the app: on the Documents step of a document base's setup, choose Connect Google Drive. You are sent to Google, you consent, and you come back with a connection linked to your workspace. Tokens are encrypted at rest and a disconnect revokes them upstream.

The connection id is what the API calls need afterwards. The app shows it on the connection, and GET /connectors/connections lists them. That route belongs to the console rather than to the published contract, so it has no /v1 form and may change with the app.

Adding documents to a base that is already live is the same trip. Add documents on the Documents tab opens the wizard's Documents step, the import runs there, and the wizard carries on to the model, the review and onboarding, so the new documents are live at the end of it rather than sitting in a base that still answers from the old ones.

2. Import files once, or register a source

Two different jobs, and it is worth picking deliberately.

A one-off import pulls what you picked, right now, and stops. It is what the onboarding wizard runs:

curl -X POST https://api.engramdynamics.org/v1/corpora/c_7a1f.../import \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{
        "connection_id": "cc_2d91...",
        "folder_id": "1AbCdEfGhIjKlMnOpQrS",
        "folder_name": "Support handbook"
      }'

curl https://api.engramdynamics.org/v1/corpora/c_7a1f.../import-status \
  -H "Authorization: Bearer <your key>"

A source is a standing connection: it syncs on a schedule and fetches only what Google says changed.

curl -X POST https://api.engramdynamics.org/v1/corpora/c_7a1f.../sources \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{
        "kind": "google_drive",
        "connection_id": "cc_2d91...",
        "folder_id": "1AbCdEfGhIjKlMnOpQrS",
        "mode": "additive",
        "schedule_minutes": 60
      }'

There is no IAM step and no template, because the OAuth connection is the credential. Registration comes back ready immediately and does not walk the folder first: the connection was proven when it was linked, and a folder id that turns out to be wrong surfaces as a failed run carrying Google's own reason, which beats making every registration wait 30 seconds to learn something the first sync learns anyway.

A connection that belongs to another provider is a 422, another workspace's connection is a 404, and registering the same folder twice on one base is a 409.

What comes across

In Drive	In your document base
Google Docs	Exported as `.docx` and read normally
Google Sheets	Exported as `.xlsx` and read normally
PDF, Word, HTML, Markdown, text, CSV and the rest of the accepted list	Read as they are
Google Forms, Sites and other native types with no useful text export	Counted as skipped, not silently dropped
Anything over the per-object ceiling	Refused mid-download rather than buffered

A file you explicitly picked and that we cannot handle is reported as skipped, because a file someone chose disappearing without a word is exactly what makes an import read as a mysterious zero-added run. The accepted types are on What counts as a document.

How updates are picked up

The first sync establishes a baseline. After that we hold a change cursor and ask Google what has moved since, so a folder of five thousand files with three changes fetches three files. has_delta_token on the source says the cursor is held and the next sync will be incremental.

Two behaviours follow from how Drive's change feed works. The feed is per account rather than per folder, so we filter changes back down to the folder you registered. And a trashed or removed file comes back as a removal, which a source in mirror mode acts on and one in additive mode ignores.

curl -X POST https://api.engramdynamics.org/v1/corpora/c_7a1f.../sources/s_9d21.../sync \
  -H "Authorization: Bearer <your key>"

When nothing arrives

The run added zero documents. Almost always a folder pick. Re-pick the files themselves in the Picker, which is what creates the grant.
Google would not give Engram read access to the folder. Picking a folder asks Google to share it with Engram's reading account, and Google can refuse. The message names its reason: a sharing limit clears on its own, so wait a few minutes and pick the folder again, and anything else means picking the files themselves, or a folder you own, gets you there now.
Files are listed as skipped. Check the type: Forms and Sites have no text export, and an unsupported extension is refused at the edge rather than stored.
The sync fails with an authorization error. The connection needs re-linking, which usually means someone revoked access in their Google account. Reconnect in the app; the flow is idempotent and re-encrypts the tokens in place.
Google Drive is not offered at all. The connector is off in that environment. Use S3 or the CLI in the meantime.

Turning a folder into a standing source from the Sources section of the Documents tab, on a schedule you pick: Keeping a folder in sync. Doing the same from Microsoft 365: SharePoint.