Connectors overview

Connect external platforms to automatically sync documents into supermemory. Supported connectors include Google Drive, Gmail, Notion, OneDrive, GitHub, Granola and Web Crawler with real-time synchronization and intelligent content processing. New v5 connectors belong to one namespace. The namespace goes in the URL (/ns/{namespace}/connectors) and is the first argument of namespace-scoped SDK calls. Organization-wide listing uses connectors.listAll() in TypeScript or connectors.list_all() in Python without a namespace argument. Legacy connectors can span multiple namespaces or have no namespace.

Supported connectors

Google Drive

Google Docs, Slides, SheetsReal-time sync via webhooks. Supports shared drives, nested folders, and collaborative documents.

Gmail

Email ThreadsReal-time sync via Pub/Sub webhooks. Syncs threads with full conversation history and metadata.

Notion

Pages, Databases, BlocksInstant sync of workspace content. Handles rich formatting, embeds, and database properties.

OneDrive

Word, Excel, PowerPointReal-time updates via webhooks. Supports personal and business accounts with file versioning.

GitHub

GitHub RepositoriesReal-time incremental sync via webhooks. Supports documentation files in repositories.

Granola

Meeting notes and transcriptsSyncs AI meeting notes, summaries, attendees, and transcripts from your Granola workspace.

Web Crawler

Web Pages, DocumentationCrawl websites automatically with robots.txt compliance. Scheduled recrawling keeps content up to date.

Quick start

1. Create a Connector

import { Supermemory } from "supermemory"

const supermemory = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY })

const connector = await supermemory.connectors.create("user-123", {
  provider: "notion",
  redirectUrl: "https://yourapp.com/callback",
  documentLimit: 5000,
})

// Send the user to authorization.url to finish OAuth
console.log("Connector:", connector.id)
console.log("Auth URL:", connector.authorization?.url)
console.log("Expires at:", connector.authorization?.expiresAt)
// Output: Auth URL: https://api.supermemory.ai/v3/connections/auth/redirect?state=...

from supermemory import Supermemory
import os

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

connector = client.connectors.create(
    "user-123",
    request={
        "provider": "notion",
        "redirect_url": "https://yourapp.com/callback",
        "document_limit": 5000,
    },
)

# Send the user to authorization.url to finish OAuth
print(f"Connector: {connector.id}")
print(f"Auth URL: {connector.authorization.url}")
print(f"Expires at: {connector.authorization.expires_at}")
# Output: Auth URL: https://api.supermemory.ai/v3/connections/auth/redirect?state=...

curl -X POST "https://api.supermemory.ai/ns/user-123/connectors" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "notion",
    "redirectUrl": "https://yourapp.com/callback",
    "documentLimit": 5000
  }'

# Response: {
#   "id": "PTzGiUYei7pgzg5buzZHgA",
#   "authorization": {
#     "url": "https://api.supermemory.ai/v3/connections/auth/redirect?state=...",
#     "expiresAt": "2024-01-15T11:30:00.000Z"
#   }
# }

2. Handle OAuth callback

Send the user to authorization.url before authorization.expiresAt. When the user authorizes, the provider returns them to your redirectUrl and the first sync starts. GitHub and Gmail, and Google Drive and OneDrive with the default syncScope: "selected", first send the user through Supermemory’s hosted picker to choose what to sync. A pending OAuth connector is not returned by list until the user finishes authorization; get returns it with system.status: "pending_authorization". Config providers (Web Crawler, S3, Granola) return authorization: null and start syncing immediately.

3. Monitor sync status

import { Supermemory } from "supermemory"

const supermemory = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY })

// Read one connector with its recent sync runs
const connector = await supermemory.connectors.get("user-123", "PTzGiUYei7pgzg5buzZHgA", {
  include: "syncs",
})

console.log("Provider:", connector.provider)
console.log("Account:", connector.account)
console.log("Last sync:", connector.latestRun?.system.status, connector.latestRun?.error)
console.log("Last synced at:", connector.system.lastSuccessfulSyncAt)
console.log("Documents:", connector.documentCount)
console.log("Recent runs:", connector.syncs)

// List the documents the connector synced into the namespace
const docs = await supermemory.list("user-123", "documents")
console.log(`Synced ${docs.pagination.totalItems} documents`)
// Output: Synced 45 documents

from supermemory import Supermemory
import os

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

# Read one connector with its recent sync runs
connector = client.connectors.get("user-123", "PTzGiUYei7pgzg5buzZHgA", include=["syncs"])

print(f"Provider: {connector.provider}")
print(f"Account: {connector.account}")
print(f"Last sync: {connector.latest_run.system.status if connector.latest_run else 'never'}")
if connector.latest_run and connector.latest_run.error:
    print(connector.latest_run.error)
print(f"Last synced at: {connector.system.last_successful_sync_at}")
print(f"Documents: {connector.document_count}")
print(f"Recent runs: {connector.syncs}")

# List the documents the connector synced into the namespace
docs = client.list("user-123", "documents")
print(f"Synced {docs.pagination.total_items} documents")
# Output: Synced 45 documents

# Read one connector with its recent sync runs
curl "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA?include=syncs" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

# Response: {
#   "id": "PTzGiUYei7pgzg5buzZHgA",
#   "provider": "notion",
#   "namespace": "user-123",
#   "account": "user@example.com",
#   "documentLimit": 5000,
#   "documentCount": 45,
#   "latestRun": { "errorCode": null, "error": null, "system": { "status": "completed", "startedAt": "...", "completedAt": "..." } },
#   "system": { "status": "active", "createdAt": "2024-01-15T10:30:00.000Z", "lastSuccessfulSyncAt": "2024-01-15T10:45:00.000Z" },
#   "syncs": [...]
# }

# List synced documents in the namespace
curl -X POST "https://api.supermemory.ai/ns/user-123/list/documents" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Response: {"documents": [...], "pagination": {"totalItems": 45, ...}}

How connectors work

Authentication flow

Create Connector: Call POST /ns/{namespace}/connectors with a provider. OAuth providers return an authorization link; config providers (Web Crawler, S3, Granola) take a config object and return authorization: null
User Authorization: Send the user to authorization.url when the provider requires it
Automatic Setup: The connector is established. Save any required label, repository, or file selection before content sync can proceed; providers without a selection step start their initial sync after setup
Continuous Sync: Real-time updates via webhooks (or scheduled recrawling for Web Crawler), plus manual sync on demand

Document processing pipeline

Sync mechanisms

Provider	Real-time Sync	Scheduled Sync	Manual Sync
Google Drive	✅ Webhooks (7-day expiry)	❌ Not supported	✅ On-demand
Gmail	✅ Pub/Sub (7-day expiry)	❌ Not supported	✅ On-demand
Notion	✅ Webhooks	❌ Not supported	✅ On-demand
OneDrive	✅ Webhooks (30-day expiry)	❌ Not supported	✅ On-demand
GitHub	✅ Webhooks	❌ Not supported	✅ On-demand
Granola	❌ Not supported	❌ Not supported	✅ On-demand
Web Crawler	❌ Not supported	✅ Scheduled recrawling (7+ days)	✅ On-demand

Connector Management

List Connectors

import { Supermemory } from "supermemory"

const supermemory = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY })

// Connectors in one namespace
const { connectors } = await supermemory.connectors.list("org-123")

for (const connector of connectors) {
  console.log(`${connector.provider}: ${connector.account} (${connector.id})`)
  console.log(`Documents: ${connector.documentCount} of ${connector.documentLimit}`)
  console.log(`Last sync: ${connector.latestRun?.system.status ?? "never"}`)
}

// Connectors across every namespace in the organization
const all = await supermemory.connectors.listAll()

from supermemory import Supermemory
import os

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

# Connectors in one namespace
connectors = client.connectors.list("org-123").connectors

for connector in connectors:
    print(f"{connector.provider}: {connector.account} ({connector.id})")
    print(f"Documents: {connector.document_count} of {connector.document_limit}")
    print(f"Last sync: {connector.latest_run.system.status if connector.latest_run else 'never'}")

# Connectors across every namespace in the organization
all_connectors = client.connectors.list_all()

# Connectors in one namespace
curl "https://api.supermemory.ai/ns/org-123/connectors" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

# Response: {
#   "connectors": [
#     {
#       "id": "PTzGiUYei7pgzg5buzZHgA",
#       "provider": "notion",
#       "namespace": "org-123",
#       "account": "user@company.com",
#       "documentLimit": 5000,
#       "documentCount": 45,
#       "latestRun": { "system": { "status": "completed", ... }, "error": null },
#       "system": { "status": "active", "createdAt": "2024-01-15T10:30:00.000Z", "lastSuccessfulSyncAt": "2024-01-15T10:45:00.000Z" }
#     }
#   ],
#   "pagination": { "currentPage": 1, "limit": 10, "totalItems": 1, "totalPages": 1 }
# }

# Connectors across every namespace in the organization
curl "https://api.supermemory.ai/connectors" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

Trigger a Sync

A connector syncs on its own schedule. Start one now with connectors.sync. The call returns 409 while a sync for that connector is already running.

const run = await supermemory.connectors.sync("org-123", "PTzGiUYei7pgzg5buzZHgA")

console.log(run.status)
// Output: queued

curl -X POST "https://api.supermemory.ai/ns/org-123/connectors/PTzGiUYei7pgzg5buzZHgA/sync" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

# Response: {"id": "PTzGiUYei7pgzg5buzZHgA", "status": "queued"}

Update a Connector

Change the document limit, or the selection for providers that support one, with connectors.update. A new selection replaces the old one. See Managing Connector Selection.

const connector = await supermemory.connectors.update("org-123", "PTzGiUYei7pgzg5buzZHgA", {
  documentLimit: 8000,
})

console.log(connector.documentLimit)
// Output: 8000

curl -X PATCH "https://api.supermemory.ai/ns/org-123/connectors/PTzGiUYei7pgzg5buzZHgA" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"documentLimit": 8000}'

# Response: the updated connector object

Delete Connectors

DELETE /ns/{namespace}/connectors/{id} accepts an optional deleteDocuments query parameter:

Parameter	Type	Default	Description
`deleteDocuments`	boolean	`true`	When `true`, all documents imported by the connector are permanently deleted. When `false`, the connector is removed but documents are kept.

Setting deleteDocuments=false is useful when you want to disconnect an integration without losing the memories that were already imported.

import { Supermemory } from "supermemory"

const supermemory = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY })

// Delete the connector and all imported documents (default)
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA")

// Delete the connector but keep imported documents
await supermemory.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", {
  deleteDocuments: false,
})

from supermemory import Supermemory
import os

client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

# Delete the connector and all imported documents (default)
client.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA")

# Delete the connector but keep imported documents
client.connectors.delete("user-123", "PTzGiUYei7pgzg5buzZHgA", delete_documents=False)

# Delete the connector and all imported documents (default)
curl -X DELETE "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

# Delete the connector but keep imported documents
curl -X DELETE "https://api.supermemory.ai/ns/user-123/connectors/PTzGiUYei7pgzg5buzZHgA?deleteDocuments=false" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

There is no delete-by-provider route in v5. Find the connector with connectors.list(namespace) and delete it by id.

Custom OAuth applications

By default, Supermemory uses its own OAuth applications to connect to third-party providers. You can use your own OAuth app credentials for tighter control over data access, which is useful for enterprise customers. Custom OAuth credentials are an organization setting and are not part of the v5 connector routes.

Create the OAuth application on the provider’s developer console:
- Google: console.developers.google.com/apis/credentials/oauthclient
- Notion: notion.so/my-integrations
- OneDrive: Azure Portal → App registrations
For Google Drive specifically: choose application type Web application, and enable the Google Drive API under “APIs and Services” in the Cloud Console. Google also requires verification/approval before custom keys work in production.
Set the redirect URL to https://api.supermemory.ai/v3/connections/auth/callback/{provider} (for example, .../auth/callback/google-drive).

Enabling custom keys for a provider applies to all new connectors for that provider. Existing connectors will need to be re-authorized.

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Supported connectors

Google Drive

Gmail

Notion

OneDrive

GitHub

Granola

Web Crawler

Quick start

1. Create a Connector

2. Handle OAuth callback

3. Monitor sync status

How connectors work

Authentication flow

Document processing pipeline

Sync mechanisms

Connector Management

List Connectors

Trigger a Sync

Update a Connector

Delete Connectors

Custom OAuth applications

​Supported connectors

Google Drive

Gmail

Notion

OneDrive

GitHub

Granola

Web Crawler

​Quick start

​1. Create a Connector

​2. Handle OAuth callback

​3. Monitor sync status

​How connectors work

​Authentication flow

​Document processing pipeline

​Sync mechanisms

​Connector Management

​List Connectors

​Trigger a Sync

​Update a Connector

​Delete Connectors

​Custom OAuth applications

Supported connectors

Quick start

1. Create a Connector

2. Handle OAuth callback

3. Monitor sync status

How connectors work

Authentication flow

Document processing pipeline

Sync mechanisms

Connector Management

List Connectors

Trigger a Sync

Update a Connector

Delete Connectors

Custom OAuth applications