SDK Reference
Connectors & Sync

Connectors & Sync

Connectors let Grounded pull data from external systems into the existing session and insight workflows.

The SDK currently uses the backend's existing connector model:

type ConnectorCategory = 'llm-tracing' | 'session-data';

Current Connector Surface

grounded.connectors.list()
grounded.connectors.get(connectorId)
grounded.connectors.create(input)
grounded.connectors.update(connectorId, input)
grounded.connectors.connect(connectorId, { config? })
grounded.connectors.disconnect(connectorId)
grounded.connectors.sync(connectorId)
grounded.connectors.delete(connectorId)

Create A Connector

const connector = await grounded.connectors.create({
  agentId: 'agt_123',
  name: 'LangSmith prod',
  category: 'llm-tracing',
  config: {
    apiKey: process.env.LANGSMITH_API_KEY!,
    projectName: 'support-prod',
  },
});

The current SDK keeps config as Record<string, string>. Provider-specific config typing and validation are still mostly a backend concern right now.

Update Without Reconnecting

PATCH /api/connectors/:connectorId was added specifically so the SDK can update connector config without forcing a reconnect flow.

await grounded.connectors.update(connector.id, {
  name: 'LangSmith production',
  config: {
    apiKey: process.env.LANGSMITH_API_KEY!,
    projectName: 'support-prod-v2',
  },
});

Connect

connect() does two things:

  1. marks the connector as connected
  2. enqueues a sync job immediately
const result = await grounded.connectors.connect(connector.id);
 
console.log(result.status); // connected
console.log(result.jobId);  // sync_...

Sync Directly

sync() exists for the case where the connector is already configured and you want to enqueue a fresh sync job programmatically.

const syncJob = await grounded.connectors.sync(connector.id);
await grounded.jobs.wait(syncJob.id);

The direct sync endpoint returns a minimal job record:

{
  id: 'sync_...',
  status: 'queued'
}

Disconnect

Disconnecting only changes connector state. It does not delete historical synced data.

await grounded.connectors.disconnect(connector.id);

Common Pattern

const connector = await grounded.connectors.create({
  agentId: 'agt_123',
  name: 'FullStory support',
  category: 'session-data',
  config: {
    apiKey: process.env.FULLSTORY_API_KEY!,
    segmentId: 'support-prod',
  },
});
 
await grounded.connectors.connect(connector.id);
 
const sync = await grounded.connectors.sync(connector.id);
const job = await grounded.jobs.wait(sync.id, {
  timeoutMs: 30 * 60_000,
});
 
const summary = await grounded.jobs.summary(job.id);

Notes

  • list and get operations respect API-key scoping
  • agent-scoped keys can only touch that agent's connectors
  • tenant-scoped keys can list connectors across agents in the same tenant
Client ReferenceSnapshots & Jobs