Skip to main content

Connectors API

Manage data source connectors programmatically.

List Connectors​

Endpoint​

GET /api/v1/connectors

Response​

{
  "data": [
    {
      "id": "conn_abc123",
      "name": "Engineering Confluence",
      "type": "confluence",
      "status": "active",
      "collection": "col_xyz",
      "lastSync": "2024-01-20T14:00:00Z",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Create Connector​

Endpoint​

POST /api/v1/connectors

Request Body (S3 Example)​

{
  "name": "Document Storage",
  "type": "s3",
  "collection": "col_abc123",
  "config": {
    "bucket": "my-documents",
    "region": "us-east-1",
    "prefix": "/documents/"
  },
  "credentials": {
    "accessKeyId": "AKIA...",
    "secretAccessKey": "..."
  }
}

Connector Types​

TypeConfig Fields
s3bucket, region, prefix, endpoint
google_driveOAuth handled separately
confluenceinstanceUrl, spaceKeys
githubrepos, branch, pathFilter
slackchannels, dateRange
notionOAuth handled separately
salesforceobjects, soqlFilter
postgresqlhost, port, database, schema

Get Connector​

Endpoint​

GET /api/v1/connectors/{id}

Update Connector​

Endpoint​

PUT /api/v1/connectors/{id}

Request Body​

{
  "name": "Updated Name",
  "config": {
    "prefix": "/new-prefix/"
  }
}

Delete Connector​

Endpoint​

DELETE /api/v1/connectors/{id}

Trigger Sync​

Endpoint​

POST /api/v1/connectors/{id}/sync

Request Body (Optional)​

{
  "sync_mode": "full",
  "file_filter": ["path/to/specific/file.pdf"]
}

Parameters​

ParameterTypeRequiredDescription
sync_modestringNoSync strategy: full, incremental, or auto (default)
file_filterstring[]NoSpecific file paths to sync (used with incremental mode)
force_full_syncbooleanNoAlias for sync_mode: "full" (deprecated)

Sync Modes​

ModeDescriptionUse Case
autoDefault behavior. Uses incremental sync if file_filter provided, otherwise full scan. Applies idempotency check to skip recently processed documents.Scheduled syncs, normal operations
fullReprocesses ALL documents regardless of file_filter. Bypasses idempotency check.Complete reindex, schema changes, troubleshooting
incrementalProcesses ONLY files in file_filter. Bypasses idempotency check.Webhook-triggered updates, targeted refreshes
When to use each mode
  • auto (default): Best for regular scheduled syncs. Efficiently skips unchanged documents.
  • full: Use when you need to reprocess everything, such as after changing embedding models or fixing data issues.
  • incremental: Use when you know exactly which files changed (e.g., from a webhook notification).

Response​

{
  "data": {
    "jobId": "job_abc123",
    "status": "queued",
    "startedAt": "2024-01-20T14:00:00Z"
  }
}

Get Sync Status​

Endpoint​

GET /api/v1/connectors/{id}/sync/{jobId}

Response​

{
  "data": {
    "jobId": "job_abc123",
    "status": "running",
    "progress": {
      "collected": 150,
      "parsed": 120,
      "indexed": 100
    },
    "startedAt": "2024-01-20T14:00:00Z"
  }
}

Test Connection​

Test Existing Connector​

POST /api/v1/connectors/{id}/test

Test an existing connector's connection to its data source.

Test Credentials​

POST /api/v1/connectors/test

Test connection credentials before creating a connector.

Connector Documents​

List Documents​

GET /api/v1/connectors/{id}/documents

Get Document​

GET /api/v1/connectors/{id}/documents/{documentId}

Delete Document​

DELETE /api/v1/connectors/{id}/documents/{documentId}

Source Files​

List Source Files​

GET /api/v1/connectors/{id}/files

Upload Files​

POST /api/v1/connectors/{id}/files/upload

Delete Files​

DELETE /api/v1/connectors/{id}/files

Refresh Permissions​

POST /api/v1/connectors/{id}/refresh-permissions

Re-sync document permissions from the source platform.

OAuth Connectors​

For OAuth-based connectors:

Initialize OAuth​

POST /api/v1/oauth/init

OAuth Callback​

GET /api/v1/oauth/callback/{provider}

Example Usage​

Create S3 Connector​

const connector = await client.connectors.create({
  name: 'Document Storage',
  type: 's3',
  collection: 'col_abc123',
  config: {
    bucket: 'my-docs',
    region: 'us-east-1'
  },
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY,
    secretAccessKey: process.env.AWS_SECRET_KEY
  }
});

Trigger Sync​

const job = await client.connectors.sync('conn_abc123');
console.log('Sync started:', job.jobId);

Next Steps​