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 connectors that sync everything.

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}")

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
401: Unauthorized
404: Connector not found

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; the connector becomes visible once they authorize
if (created.authorization) window.location.href = created.authorization.url

// 3. After the callback, open the hosted picker so the user chooses repositories
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",
        "redirectUrl": "https://yourapp.com/callback",
    },
)

# 2. Send the user to GitHub; the connector becomes visible once they authorize
print(f"Redirect to: {created.authorization.url}")

# 3. After the callback, open the hosted picker so the user chooses repositories
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) ...

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