Python SDK

Install, configure, and handle lifecycle and errors with the Viio Sync API Python SDK.

Last updated August 6, 2026

This guide covers behavior specific to viio-sync-api-sdk 0.2.0. For record types and fields, use the Model Reference.

Installation

python -m pip install viio-sync-api-sdk==0.2.0

Python 3.11 and later are supported.

Usage

from viio_sync_api import SyncApiAuthentication, SyncApiClient, SyncApiClientOptions
from viio_sync_api.v1 import Account, AccountRecords, GenericAccountDetails, SyncRecordsRequest


options = SyncApiClientOptions(
    endpoint="https://sync.viio.io",
    authentication=SyncApiAuthentication.api_key(api_key),
)

async with SyncApiClient(options) as client:
    batch = await client.start_batch(installation_id)
    try:
        await batch.write(
            SyncRecordsRequest(
                accounts=AccountRecords(
                    records=[
                        Account(
                            generic=GenericAccountDetails(
                                id="account-1",
                                email="person@example.com",
                            )
                        )
                    ]
                )
            )
        )
        await batch.complete()
    except BaseException:
        await batch.abort()
        raise

Client Configuration

Field	Required	Default	Description
`endpoint`	Yes	—	HTTPS Sync API endpoint; HTTP is allowed only for loopback development
`authentication`	Yes	—	API-key or Viio-managed authentication
`max_receive_message_size`	No	16 MiB	Maximum response-message size accepted by the client
`max_send_message_size`	No	gRPC default	Maximum request-message size
`timeout`	No	100 seconds	Positive per-operation timeout

Customer-managed integrations use SyncApiAuthentication.api_key(api_key). The key must have the integration:sync permission and belong to the target installation's workspace.

Batch Lifecycle

Member	Description
`batch_id`	Server-generated batch identifier
`await write(request)`	Send one typed collection
`await complete()`	Complete the batch and make the local handle terminal
`await abort()`	Abort the batch and make the local handle terminal
`close()`	Release local resources without completing or aborting the server batch

Writes are serialized. A successful completion or abort rejects later operations on the same batch object.

Error Handling

Error	Meaning
`SyncApiBatchAlreadyInProgressError`	Another batch owns the installation lock
`SyncApiProtocolError`	The server rejected an SDK operation
`SyncApiAuthenticationError`	Authentication could not produce a usable credential
`SyncApiBatchStateError`	The batch was already completed or aborted
`SyncApiClosedError`	The client or batch was closed
`grpc.aio.AioRpcError`	Transport or server RPC failure
`TypeError` or `ValueError`	Invalid client input or configuration

For retry and abort guidance, see the Quickstart.

Requests and Models

write accepts SyncRecordsRequest. Set exactly one typed collection per call; the SDK adds batch_id automatically.

The dedicated Model Reference lists every supported collection and record field, including its Python name, type, and requiredness.