---
title: Connectors Reference
path: reference/connectors
status: published
---

SMB and SharePoint connector endpoints. For conceptual guides, see [SMB Connector](/docs/scaidrive/connectors/smb-connector) and [SharePoint Connector](/docs/scaidrive/connectors/sharepoint-connector).

**Base paths:** `/api/v1/smb-connectors/`, `/api/v1/sharepoint-connectors/`

## SMB Connectors

### Connector object

```json
{
  "id": "cnn_01J5X",
  "name": "Finance Fileserver",
  "description": "Legacy Windows share",
  "server_host": "fs01.corp.example.com",
  "server_port": 445,
  "share_name": "Finance",
  "base_path": "2026",
  "domain": "CORP",
  "username": "scaidrive-svc",
  "target_share_id": "shr_01J3H",
  "target_path": "/From Fileserver",
  "sync_direction": "bidirectional",
  "sync_permissions": true,
  "sync_hidden_files": false,
  "sync_system_files": false,
  "include_patterns": {"extensions": ["pdf", "docx", "xlsx"]},
  "exclude_patterns": {"patterns": ["~$*"]},
  "conflict_resolution": "LAST_WRITER_WINS",
  "sync_interval_minutes": 15,
  "status": "idle",
  "status_message": null,
  "error_count": 0,
  "last_sync_at": "2026-04-23T09:45:00Z",
  "next_sync_at": "2026-04-23T10:00:00Z",
  "total_files_synced": 8420,
  "total_bytes_synced": 45923847621
}
```

Password is write-only — never returned.

### GET /api/v1/smb-connectors

List tenant's SMB connectors.

### POST /api/v1/smb-connectors

Create. Returns 201.

**Required permission:** `MANAGE_PERMISSIONS` on target share.

### GET /api/v1/smb-connectors/{connector_id}

### PATCH /api/v1/smb-connectors/{connector_id}

Update. Any field except `target_share_id`.

### DELETE /api/v1/smb-connectors/{connector_id}

Returns 204.

### POST /api/v1/smb-connectors/{connector_id}/test

Test connectivity.

**Response:** `{success, message, error}`.

### POST /api/v1/smb-connectors/{connector_id}/sync

Trigger manual sync. Returns 202.

**Query:** `full_sync` (boolean, default false).

**Response:** `{job_id, started_at}`.

### GET /api/v1/smb-connectors/{connector_id}/jobs

List sync jobs.

**Query:** `limit`, `offset`, `status` (`running`, `completed`, `failed`).

**Response:** `{jobs: [...]}`. Each job: `id`, `status`, `started_at`, `finished_at`, `files_scanned`, `files_synced`, `bytes_transferred`, `error_count`.

### GET /api/v1/smb-connectors/{connector_id}/file-states

Per-file sync tracking.

**Query:** `limit`, `offset`, `status`.

### Identity mappings

#### POST /api/v1/smb-connectors/{connector_id}/identity-mappings

**Body:**

```json
{
  "identity_type": "user",
  "smb_principal": "CORP\\alice",
  "scaidrive_principal_id": "usr_01J4M"
}
```

Returns 201.

#### GET /api/v1/smb-connectors/{connector_id}/identity-mappings

#### DELETE /api/v1/smb-connectors/{connector_id}/identity-mappings/{mapping_id}

Returns 204.

## SharePoint Connectors

Same shape as SMB with these extra fields on the connector object:

```json
{
  "site_url": "https://contoso.sharepoint.com/sites/marketing",
  "site_id": "contoso.sharepoint.com,abc...",
  "drive_id": "b!xyz...",
  "library_name": "Documents",
  "azure_tenant_id": "11111...",
  "azure_client_id": "22222...",
  "auth_type": "app_auth",
  "sync_versions": true,
  "sync_metadata": true
}
```

`azure_client_secret` is write-only.

### GET, POST, PATCH, DELETE /api/v1/sharepoint-connectors/{...}

Mirrors the SMB connector endpoints.

### POST /api/v1/sharepoint-connectors/{connector_id}/authorize

Start OAuth flow (for `user_auth` mode).

**Response:** `{authorization_url, state}`.

### POST /api/v1/sharepoint-connectors/{connector_id}/test

### POST /api/v1/sharepoint-connectors/{connector_id}/sync

### GET /api/v1/sharepoint-connectors/{connector_id}/jobs

### GET /api/v1/sharepoint-connectors/{connector_id}/file-states

### Azure identity helpers

#### POST /api/v1/sharepoint-connectors/{connector_id}/azure/users/search

**Body:** `{"query": "alice"}`.

**Response:** `{users: [{id, email, name}]}`.

#### POST /api/v1/sharepoint-connectors/{connector_id}/azure/groups/search

**Body:** `{"query": "marketing"}`.

### Identity mappings

Same endpoints as SMB — `/identity-mappings`. The `smb_principal` field carries the Azure AD object ID for SharePoint connectors.

## Error codes

| Code | HTTP | When |
|------|------|------|
| `CONNECTOR_UNREACHABLE` | 502 | Source not reachable |
| `CONNECTOR_AUTH_FAILED` | 401 | Source auth rejected |
| `CONNECTOR_SYNC_IN_PROGRESS` | 409 | Another sync already running |

## Related

- [SMB Connector Guide](/docs/scaidrive/connectors/smb-connector)
- [SharePoint Connector Guide](/docs/scaidrive/connectors/sharepoint-connector)