> Documentation index: [/llms.txt](/llms.txt). Every page as one file: [/llms-full.txt](/llms-full.txt). # SharePoint sync SharePoint sync [#sharepoint-sync] Learn how a SharePoint sync source imports files into Alo Files and what happens when SharePoint or the connection changes. A SharePoint sync source imports files and folders from SharePoint into an Alo Files workspace through a Central Hub SharePoint connection. Alo Files stores the content in its workspace and keeps the remote mapping, so the files are searchable and usable as Agent knowledge. How it works [#how-it-works] * A source starts from a SharePoint connection in Central Hub, created or re-authenticated there. * The source names a site, a drive (document library), and file or folder roots, and is created with `POST /connector-syncs/sharepoint` and a destination folder. * `GET /contents` lists the imported files and folders with their sync and ingestion status. * A source is refreshed with the connector-sync endpoints when needed; each refresh is a run you can poll. | Situation | Behavior | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The connection needs re-authentication | Syncing returns `409` with `details.reason` `sharepoint_reconnect_required`. Reconnect the Central Hub connection, or sync with `replacement_connection_id` set to another SharePoint connection that can read the same site and drive. | | Item deleted remotely | The item is listed in the source's `pending_deletions`; keep the imported item as a local copy, or delete it from Alo Files. | | Another member syncs your source | Refused with `409` and `details.reason` `sharepoint_connection_required`: a source is private to the person who created it, though its imported files are visible to the workspace. | Boundaries [#boundaries] * A sync source is not a SharePoint connection of its own: imports reuse the Central Hub connection, so reconnecting happens in Central Hub. * Source-managed items are not reorganized locally: renaming or moving one in Alo Files returns `409` with `details.reason` `managed_by_sync`, because the remote hierarchy is authoritative. Reference [#reference] Endpoints [#endpoints] | Action | Endpoint | Body | Returns | Auth | | ------------------------ | --------------------------------------------------- | ----------------------------------------- | ------------------- | ------------- | | Create a source | `POST /connector-syncs/sharepoint` | See [Create body](#create-body) | `202` `{sync, run}` | Key or bearer | | List your sources | `GET /connector-syncs` | None | List of sources | Key or bearer | | Get a source | `GET /connector-syncs/{sync_id}` | None | Source | Key or bearer | | Sync a source | `POST /connector-syncs/{sync_id}/sync` | Optional `{replacement_connection_id}` | `202`, run | Key or bearer | | Sync all your sources | `POST /connector-syncs/sync-all` | None | `202` `{runs}` | Key or bearer | | Get a run | `GET /connector-sync-runs/{run_id}` | None | Run | Key or bearer | | Resolve remote deletions | `POST /connector-syncs/{sync_id}/resolve-deletions` | `{"items": [{"sync_item_id", "action"}]}` | `{deleted, kept}` | Key or bearer | | Delete a source | `DELETE /connector-syncs/{sync_id}?files=keep` | None | `204` | Key or bearer | * `POST /connector-syncs/{sync_id}/sync` takes an optional `?remote_item_id=` to sync one item of the source. If the source already has an active run, you get that run. * `POST /connector-syncs/sync-all` skips sources whose connection cannot be used. * A run has `state`, `last_error`, and `counts`: `added`, `changed`, `unchanged`, `moved`, `unsupported`, `failed`, `deleted`, `pending_deletion`. * In resolve-deletions, `action` is `keep` or `delete`, and each `sync_item_id` must come from the source's `pending_deletions` (`400` otherwise). * Deleting a source with `files=keep` (the default) leaves the imported files and folders in place; `files=delete` deletes them too. * Other members get `404` from every endpoint for your source, except sync, which returns `409` `sharepoint_connection_required`. Create body [#create-body] | Field | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------- | | `connection_id` | The Central Hub SharePoint connection | | `site_id` | The SharePoint site | | `drive_id` | The drive (document library) in that site | | `roots` | Items to import: at least one, each `item_id` unique, `[{"item_id": "…", "kind": "file"}]` with `kind` `file` or `folder` | | `parent_id` | Optional destination folder ID, `root`, or `null`; the folder must be visible to the whole workspace (`400` otherwise) | Creating with a connection that needs re-authentication returns `403`. Errors [#errors] | Status | `details.reason` | When | | ------ | ----------------------------------- | ------------------------------------------------------------------------------------------- | | `409` | `sharepoint_reconnect_required` | The source's connection needs re-authentication and no `replacement_connection_id` was sent | | `409` | `sharepoint_connection_required` | You sync a source another member created | | `409` | `managed_by_sync` | You rename or move an imported file or folder | | `409` | `file_not_ready` | You request a download link for a file that is still being imported | | `503` | None; `details.retryable` is `true` | The run could not be scheduled; retry |