Managing Connector Selection

Selectable connectors: GitHub (repositories), Gmail (labels) and Google Drive (files and folders) let you choose what to sync. Other connectors sync everything and return selection: null.

Some connectors let you select which resources to sync. v5 exposes this through two calls on the connector itself: read it with include: "picker" to get a hosted picker URL, or send the ids directly with connectors.update.

Open the Hosted Picker

GET /ns/{namespace}/connectors/{id}?include=picker Returns a one-time picker URL. Send the user there; Supermemory lists their resources, saves the selection and starts a sync. Pass returnUrl to choose where the picker sends the user when they finish.

import { Supermemory } from "supermemory"

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

const connector = await supermemory.connectors.get("user-123", connectorId, {
  include: "picker",
  returnUrl: "https://yourapp.com/settings/integrations"
})

console.log("Picker URL:", connector.picker?.url)
console.log("Expires at:", connector.picker?.expiresAt)
console.log("Selectable:", connector.capabilities.selectable)

from supermemory import Supermemory
import os

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

connector = client.connectors.get(
    "user-123",
    connector_id,
    include=["picker"],
    return_url="https://yourapp.com/settings/integrations",
)

print(f"Picker URL: {connector.picker.url if connector.picker else None}")
print(f"Expires at: {connector.picker.expires_at if connector.picker else None}")
print(f"Selectable: {connector.capabilities.selectable}")

curl "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}?include=picker&returnUrl=https%3A%2F%2Fyourapp.com%2Fsettings%2Fintegrations" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

Query parameters

include: picker for the hosted picker URL, syncs for recent sync runs, or syncs,picker for both
returnUrl: Optional. Where the hosted picker sends the user when they finish

Response

{
  "id": "PTzGiUYei7pgzg5buzZHgA",
  "provider": "github",
  "namespace": "user-123",
  "capabilities": { "selectable": true, "webhooks": true },
  "selection": {
    "repos": [
      { "id": "123456789", "name": "your-org/documentation" }
    ]
  },
  "picker": {
    "url": "https://...",
    "expiresAt": "2024-01-15T11:30:00.000Z"
  }
}

The picker link works once, in any browser. picker is null for providers that do not support selection. A Google Drive connector with full-drive sync can still open the picker; saving a selection switches it to scoped sync. Because the link changes what syncs, include=picker needs an admin key with write access to the namespace; otherwise the request returns 403.

Set the Selection Directly

PATCH /ns/{namespace}/connectors/{id} Send the ids to sync, grouped by kind. The new selection replaces the current one and starts a sync. Webhooks are registered for the selected resources.

import { Supermemory } from "supermemory"

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

const connector = await supermemory.connectors.update("user-123", connectorId, {
  selection: {
    repos: ["123456789", "987654321"],
  },
})

console.log("Selection:", connector.selection)
console.log("Last sync:", connector.latestRun?.system.status)

from supermemory import Supermemory
import os

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

connector = client.connectors.update(
    "user-123",
    connector_id,
    selection={"repos": ["123456789", "987654321"]},
)

print(f"Selection: {connector.selection}")
print(f"Last sync: {connector.latest_run.system.status if connector.latest_run else 'never'}")

curl -X PATCH "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": {
      "repos": ["123456789", "987654321"]
    }
  }'

Request body

{
  "selection": {
    "repos": ["123456789"]
  }
}

The selection key depends on the provider:

GitHub: repos (repository ids)
Gmail: labels (label ids, for example INBOX)
Google Drive: files and folders (Drive ids)

You can send documentLimit in the same body. Each call must include selection, documentLimit, or both.

Response

The updated connector object, including the saved selection as { id, name } pairs.

{
  "id": "PTzGiUYei7pgzg5buzZHgA",
  "provider": "github",
  "selection": {
    "repos": [
      { "id": "123456789", "name": "your-org/documentation" },
      { "id": "987654321", "name": "your-org/api-docs" }
    ]
  },
  "latestRun": { "errorCode": null, "error": null, "system": { "status": "running", "startedAt": "...", "completedAt": null } }
}

Error Responses

400: Connector does not support selection, the selection is empty or has unknown ids, or the connector needs to be reconnected
401: Unauthorized
403: The key lacks admin role or write access to the connector’s namespaces
404: Connector not found
409: Connector is still waiting for the user to finish authorizing

Automatic Sync: After a selection is saved, a sync starts for the connector. You don’t need to call connectors.sync afterwards.

Example: GitHub repository selection

Here’s a complete example for GitHub:

// 1. Create the connector
const created = await supermemory.connectors.create("user-123", {
  provider: "github",
  redirectUrl: "https://yourapp.com/callback"
})

// 2. Send the user to GitHub. After they authorize, Supermemory shows the hosted
//    repository picker, then returns them to redirectUrl
if (created.authorization) window.location.href = created.authorization.url

// 3. To change repositories later, open the hosted picker again
const connector = await supermemory.connectors.get("user-123", created.id, {
  include: "picker",
  returnUrl: "https://yourapp.com/settings/integrations"
})
if (connector.picker) window.location.href = connector.picker.url

// 4. Or, if you already know the repository ids, set them directly
await supermemory.connectors.update("user-123", created.id, {
  selection: { repos: selectedRepositoryIds },
})

# 1. Create the connector
created = client.connectors.create(
    "user-123",
    request={
        "provider": "github",
        "redirect_url": "https://yourapp.com/callback",
    },
)

# 2. Send the user to GitHub. After they authorize, Supermemory shows the hosted
#    repository picker, then returns them to redirect_url
print(f"Redirect to: {created.authorization.url}")

# 3. To change repositories later, open the hosted picker again
connector = client.connectors.get(
    "user-123",
    created.id,
    include=["picker"],
    return_url="https://yourapp.com/settings/integrations",
)
if connector.picker:
    print(f"Redirect to: {connector.picker.url}")

# 4. Or, if you already know the repository ids, set them directly
client.connectors.update(
    "user-123",
    created.id,
    selection={"repos": selected_repository_ids},
)

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

# 2. ... (user authorizes at authorization.url and picks repositories in the hosted picker) ...

# 3. To change repositories later, get a one-time hosted picker URL
curl "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}?include=picker" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY"

# 4. Or set the repositories directly
curl -X PATCH "https://api.supermemory.ai/ns/user-123/connectors/{connectorId}" \
  -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selection": {
      "repos": ["123456789"]
    }
  }'

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Open the Hosted Picker

Query parameters

Response

Set the Selection Directly

Request body

Response

Error Responses

Example: GitHub repository selection

​Open the Hosted Picker

​Query parameters

​Response

​Set the Selection Directly

​Request body

​Response

​Error Responses

​Example: GitHub repository selection

Open the Hosted Picker

Query parameters

Response

Set the Selection Directly

Request body

Response

Error Responses

Example: GitHub repository selection