Integration & Sync

Cloud integration connections and sync operations for Google Drive, OneDrive, SharePoint, and Dropbox.

GET /api/libraries/{id}/integration

Get the embedded integration for a library.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Response:

{
  "id": "integration-abc-123",
  "name": "Google Drive - Engineering",
  "type": "google-drive",
  "embedded": true,
  "libraryId": "550e8400-e29b-41d4-a716-446655440000",
  "authType": "oauth2",
  "clientId": "123456789-abcdefg.apps.googleusercontent.com",
  "authUri": "https://accounts.google.com/o/oauth2/v2/auth",
  "tokenUri": "https://oauth2.googleapis.com/token",
  "scope": "https://www.googleapis.com/auth/drive.readonly"
}

---

PUT /api/libraries/{id}/integration

Create or update the embedded integration for a library.

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Request Body:

Field	Type	Required	Description
integrationId	string (UUID)	Yes	Integration ID to associate

Example:

{
  "integrationId": "integration-xyz-789"
}

Response:

200 OK with integration details

---

GET /api/libraries/{id}/connection

Get the OAuth connection for a library's integration.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Response:

{
  "id": "conn-abc-123",
  "ownerId": "alice",
  "integrationId": "integration-abc-123",
  "tokenExpiresAt": "2024-02-10T14:30:00Z",
  "refreshTokenExpiresAt": "2024-03-10T14:30:00Z",
  "lastAuthorizedAt": "2024-02-09T10:00:00Z",
  "createdAt": "2024-01-15T09:00:00Z",
  "updatedAt": "2024-02-09T10:00:00Z"
}

---

DELETE /api/libraries/{id}/connection

Disconnect the OAuth connection (revoke access).

Authentication: Required

Permissions: Requires library:write permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Response:

204 No Content

Sync Impact

Disconnecting removes OAuth access. Scheduled syncs will fail until the connection is re-established.

---

POST /api/libraries/{id}/_sync

Manually trigger a sync from the connected cloud integration.

Authentication: Required

Permissions: Requires library:sync permission

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Request Body:

Field	Type	Default	Description
purge	boolean	false	Delete all existing files before syncing
progress	string	-	Progress tracking identifier

Example:

{
  "purge": false
}

Response:

200 OK

{
  "syncedFiles": 127,
  "addedFiles": 5,
  "updatedFiles": 12,
  "deletedFiles": 0,
  "errors": []
}

Long-Running

This endpoint may take several minutes for large libraries. Monitor progress via the progress parameter.

---

GET /api/libraries/{id}/account

Get account information for the connected integration.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Library ID or natural ID

Response:

{
  "email": "alice@example.com",
  "displayName": "Alice Johnson",
  "accountId": "google-account-123"
}