Installation

The UniteLabs SDK provides a simple interface for developers to integrate devices in their applications.

This guide is designed to help with the setup of your local development environment and send your first API request. If you are an experienced developer or want to dive right into using the UniteLabs API, the Reference is a great place to start. You will learn:

• How to setup your development environment
• How to install the latest SDK
• How to send your first API request
• How to improve the developer experience in your IDE

Prerequisites

UniteLabs requires Python 3.10 or newer. It is platform independent and works equally on Linux, macOS and Windows.

Some steps require authentication, therefore you need:

• UniteLabs Artifactory Access A username and password to install UniteLabs Python packages. UniteLabs packages are not published to PyPI — they are hosted in a private GitLab package registry. This is separate from GroundControl and the Platform; it is simply where the Python packages live.
  • Username: 32 characters separated by dashes.
    Example: 56ae938f-484c-41cc-ae54-e4f9b8814fb7
  • Password: 22 characters separated by dashes.
    Example: ahjt-Lk-e1swOPZcWYYGh-mKJ
• UniteLabs Client Credentials Client ID and secret to authenticate connections made from your local SDK installation (your code/client) to the UniteLabs API (the platform).
  • Client ID: A custom username with variable length.
  • Client Secret: 32 characters without separators.
    Example: YT1a2HFEoi8tiAwl6bv127Tqp0ZXDSru
  • Tenant Base URL: 32 characters separated by dashes.
    Example: https://acme-corp.dev.unitelabs.io
  • Tenant Auth URL: 32 characters separated by dashes.
    Example: https://auth.acme-corp.dev.unitelabs.io/realms/ad2a8e12-2bf2-45d7-9fb1-84bdf7102a8c/protocol/openid-connect/

If you are missing one of them, please reach out to your UniteLabs contact.

Install Packages

We recommend installing the UniteLabs SDK using a Python virtual environment manager such as uv, Poetry, or venv. All packages are provided in a private package registry which requires configuration and authentication.

The examples below install unitelabs-liquid-handling. This package includes the Liquid Handling SDK, while the labware library unitelabs-labware and core UniteLabs SDK (unitelabs-sdk) typically need to be installed as well. See The SDK at a Glance for the full breakdown.

machine gitlab.com
login <username>
password <password>

uv init --package my-app
cd my-app

uv add unitelabs-liquid-handling \
  --index unitelabs=https://gitlab.com/api/v4/groups/1009252/-/packages/pypi/simple

poetry config http-basic.unitelabs <username> <password>
poetry config virtualenvs.in-project true

poetry new my-app --src
cd my-app

poetry source add --priority=supplemental unitelabs \
  https://gitlab.com/api/v4/groups/1009252/-/packages/pypi/simple
poetry add --source unitelabs unitelabs-liquid-handling

machine gitlab.com
login <username>
password <password>

mkdir my-app
cd my-app
python -m venv .venv
.venv/bin/pip install -U pip

.venv/bin/pip install unitelabs-liquid-handling \
  --index-url https://gitlab.com/api/v4/groups/1009252/-/packages/pypi/simple

Authenticate Client

You need to authenticate your UniteLabs client to access the UniteLabs API on your behalf. We suggest to use python-dotenv to load the UniteLabs Client Credentials from a .env file in the root of your project.

BASE_URL=https://api.unitelabs.io/
AUTH_URL=https://auth.unitelabs.io/realms/<tenantID>/protocol/openid-connect/
CLIENT_ID=<clientID>
CLIENT_SECRET=<clientSecret>

Security note:
When using version control, make sure to exclude the .env file by e.g. adding it to the .gitignore file.

Send Your First Request

The SDK provides both asynchronous and synchronous clients. Choose based on your application's needs and personal preference:

• AsyncApiClient (recommended): For modern async/await code, better performance with concurrent operations
• SyncApiClient: For simple scripts or blocking code where async is not needed

import asyncio

from unitelabs.sdk import AsyncApiClient
from dotenv import load_dotenv


async def main():
  # Async example (recommended)
  client = AsyncApiClient()
  connectors = await client.list_services()
  for connector in connectors:
    print(connector.name)


if __name__ == "__main__":
  load_dotenv()
  asyncio.run(main())

from unitelabs.sdk import SyncApiClient
from dotenv import load_dotenv


def main():
  # Synchronous example
  client = SyncApiClient()
  connectors = client.list_services()
  for connector in connectors:
    print(connector.name)


if __name__ == "__main__":
  load_dotenv()
  main()

Run the script to verify your credentials and confirm the SDK can reach the platform. It should print the names of your connected instruments. This is just a smoke test; in real projects your entry point will vary.

Run the package's __main__.py file with:

uv run python -m my_app

poetry run python -m my_app

.venv/bin/python -m my_app

Versions

The installation defaults to the latest version. Updates on versions and the corresponding changelogs are posted in the Technical Reference Section. If a defined version is required or needs to be locked, it must be explicitly defined using the PEP 440 Version Specifier(==, !=, <, >, <=, >, >=) in the pyproject.toml.

[project]
requires-python = ">=3.10,<4.0"
dependencies = [
    "unitelabs-liquid-handling~=0.11.0",
    "python-dotenv",
]

We recommend pinning explicit versions for workflows you plan on running in production. The installed version can be checked using __version__:

from unitelabs import labware, liquid_handling, sdk

if __name__ == "__main__":
    print(sdk.__version__)
    print(labware.__version__)
    print(liquid_handling.__version__)

Run the file as explained above.

Note on client types:

• Client from unitelabs.sdk is deprecated
• Use AsyncApiClient (recommended) for async/await patterns
• Use SyncApiClient for synchronous/blocking code
• Both clients provide the same methods - the only difference is async vs sync execution

IDE Integration

VSCode

{
  "recommendations": ["ms-python.python"]
}

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.terminal.activateEnvironment": false
}

PyCharm

Details coming soon!

Jupyter Notebooks

uv add --dev ipykernel