Alo Files
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
- 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/sharepointand a destination folder. GET /contentslists 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
- 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
409withdetails.reasonmanaged_by_sync, because the remote hierarchy is authoritative.
Reference
Endpoints
| Action | Endpoint | Body | Returns | Auth |
|---|---|---|---|---|
| Create a source | POST /connector-syncs/sharepoint | See 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}/synctakes 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-allskips sources whose connection cannot be used.- A run has
state,last_error, andcounts:added,changed,unchanged,moved,unsupported,failed,deleted,pending_deletion. - In resolve-deletions,
actioniskeepordelete, and eachsync_item_idmust come from the source'spending_deletions(400otherwise). - Deleting a source with
files=keep(the default) leaves the imported files and folders in place;files=deletedeletes them too. - Other members get
404from every endpoint for your source, except sync, which returns409sharepoint_connection_required.
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
| 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 |
Parse a file without indexing it
Extract text and tables from files without adding them to search
POSTBatch Check
Space-scoped existence check for file/folder ids. Used by Central Hub's lazy self-heal of agents' ``enabled_file_scope`` (COR-1768): ids missing from the response were deleted (or never belonged to this space) and can be pruned from the agent's selection. The literal ``"root"`` is always reported as existing.