Getting Started

New version v2.0.0 of the SDK is available with major improvements and new features. See the Changelog for details and upgrade notes.

Introduction

The Labellerr SDK is a Python library designed to make interaction with the Labellerr platform simple and efficient. With this SDK, you can manage data annotations, projects, and exports seamlessly in your applications. This documentation will guide you through installing the SDK, understanding its core functionalities, and handling common errors.

Installation

To install the Labellerr SDK, use the following command:

pip install git+https://github.com/Labellerr/SDKPython.git

Obtaining API Credentials

To use the Labellerr SDK, you’ll need three credentials: api_key, api_secret, and client_id.

Create your Workspace

Create a new workspace or access your existing workspace from the dashboard.

Get your API Credentials

Visit your workspace API keys page:

https://<your-workspace-name>.labellerr.com/workspace/api-keys

From this page, you can obtain all three credentials:

API Key & Secret: Copy from the API Keys table
Client ID: Click the Show Client ID button to reveal and copy your client ID

Keep your credentials secure and never commit them to version control. Consider using environment variables or a secure configuration file.

Initialize the Client

Once you have your credentials, import and initialize the LabellerrClient. This client handles all communication with the Labellerr platform.

Understanding the SDK Structure

The Labellerr SDK uses a modular architecture that organizes functionality into specialized modules:

labellerr.client - Core client for authentication and API communication
labellerr.core.datasets - Dataset creation and management operations
labellerr.core.projects - Project creation and management operations
labellerr.core.files - File operations and metadata access
labellerr.core.schemas - Data validation and configuration models
labellerr.core.exceptions - Error handling utilities

Example Client Initialization:

Client Initialization

from labellerr.client import LabellerrClient
from labellerr.core.exceptions import LabellerrError

# Initialize the client with your API credentials
api_key = "your-api-key"
api_secret = "your-api-secret"
client_id = "your-client-id"

client = LabellerrClient(api_key, api_secret, client_id)

Common Import Patterns

Depending on your use case, you’ll import different modules:

Import Examples for Common Tasks

# For creating and managing datasets
from labellerr.core.datasets import (
    create_dataset_from_local,
    create_dataset_from_connection,
    LabellerrDataset
)
from labellerr.core.schemas import DatasetConfig

# For creating annotation templates
from labellerr.core.annotation_templates import (
    create_template,
    LabellerrAnnotationTemplate
)
from labellerr.core.schemas import (
    CreateTemplateParams,
    AnnotationQuestion,
    QuestionType
)

# For creating and managing projects
from labellerr.core.projects import create_project, LabellerrProject
from labellerr.core.schemas import CreateProjectParams, RotationConfig

# For video projects (includes keyframe operations)
from labellerr.core.projects import LabellerrVideoProject
from labellerr.core.schemas import KeyFrame

# For working with files
from labellerr.core.files import LabellerrFile

# For cloud connections
from labellerr.core.connectors import (
    LabellerrS3Connection,
    LabellerrGCSConnection,
    create_connection,
    list_connections,
    delete_connection
)

# For error handling
from labellerr.core.exceptions import LabellerrError

Replace 'your-api-key' and 'your-api-secret' with your actual credentials provided by Labellerr.

Working with Cloud Connections

The Labellerr SDK supports seamless integration with cloud storage providers like AWS S3 and Google Cloud Storage (GCS). You can create, test, list, and manage connections programmatically.

Required PermissionsBefore creating cloud connections, ensure your IAM user (S3) or Service Account (GCS) has the required permissions:

Provider	Import Permissions	Export Permissions
AWS S3	`s3:GetObject`, `s3:ListBucket`, `s3:GetBucketCors`, `s3:GetBucketLocation`, `s3:PutBucketCors`	+ `s3:PutObject`, `s3:DeleteObject`
GCS	`storage.objects.get`, `storage.objects.list`, `storage.buckets.get`, `storage.buckets.update`	+ `storage.objects.create`, `storage.objects.delete`

For detailed setup instructions, see:

Creating and Testing Connections

AWS S3 Connection
GCS Connection
List & Manage Connections

S3 Connection with Explicit Path TestingFor AWS S3 connections, you must provide a specific path to test the connection. The SDK will validate access to that exact path in your S3 bucket.

Create and Test S3 Connection

from labellerr.client import LabellerrClient
from labellerr.core.connectors import LabellerrS3Connection
from labellerr.core.schemas import AWSConnectionParams, AWSConnectionTestParams
from labellerr.core.exceptions import LabellerrError

# Initialize client
client = LabellerrClient(api_key, api_secret, client_id)

try:
    # Test S3 connection first (recommended)
    test_params = AWSConnectionTestParams(
        aws_access_key="your_aws_access_key",
        aws_secrets_key="your_aws_secret_key",
        path="s3://your-bucket-name/path/to/data",  # Explicit path required
        data_type="image",
        connection_type="import"
    )
    
    test_result = LabellerrS3Connection.test_connection(client, test_params)
    print(f"Connection test result: {test_result}")
    
    # If test succeeds, create the connection
    connection_params = AWSConnectionParams(
        client_id=client_id,
        aws_access_key="your_aws_access_key",
        aws_secrets_key="your_aws_secret_key",
        path="s3://your-bucket-name/path/to/data",
        data_type="image",
        name="My S3 Connection",
        description="Production data bucket",
        connection_type="import"
    )
    
    # create_connection automatically tests before creating
    s3_connection = LabellerrS3Connection.create_connection(client, connection_params)
    print(f"✓ S3 Connection created: {s3_connection.connection_id}")
    
except LabellerrError as e:
    print(f"Connection failed: {str(e)}")

Path Validation:

The path must be accessible with the provided credentials
Path format: s3://bucket-name/folder/subfolder
Test fails if permissions are insufficient or path doesn’t exist

GCS Connection with Service AccountFor Google Cloud Storage, you need to provide a service account JSON file. The connection test validates both credentials and path access.

Create and Test GCS Connection

from labellerr.client import LabellerrClient
from labellerr.core.connectors import LabellerrGCSConnection
from labellerr.core.schemas import GCSConnectionParams, GCSConnectionTestParams
from labellerr.core.exceptions import LabellerrError

# Initialize client
client = LabellerrClient(api_key, api_secret, client_id)

try:
    # Test GCS connection first (recommended)
    test_params = GCSConnectionTestParams(
        svc_account_json="/path/to/service-account.json",
        path="gs://your-bucket-name/path/to/data",
        data_type="image",
        connection_type="import"
    )
    
    test_result = LabellerrGCSConnection.test_connection(client, test_params)
    print(f"Connection test result: {test_result}")
    
    # If test succeeds, create the connection
    connection_params = GCSConnectionParams(
        client_id=client_id,
        svc_account_json="/path/to/service-account.json",
        path="gs://your-bucket-name/path/to/data",
        data_type="image",
        name="My GCS Connection",
        description="Production GCS bucket",
        connection_type="import"
    )
    
    # create_connection automatically tests before creating
    gcs_connection = LabellerrGCSConnection.create_connection(client, connection_params)
    print(f"✓ GCS Connection created: {gcs_connection.connection_id}")
    
except LabellerrError as e:
    print(f"Connection failed: {str(e)}")

Service Account Requirements:

Service account must have Storage Object Viewer permission (minimum)
JSON key file must be valid and accessible
Path must exist in the specified GCS bucket

List and Manage Connections

from labellerr.client import LabellerrClient
from labellerr.core.connectors import list_connections, delete_connection
from labellerr.core.schemas import ConnectorType, ConnectionType
from labellerr.core.exceptions import LabellerrError

# Initialize client
client = LabellerrClient(api_key, api_secret, client_id)

try:
    # List all S3 connections
    s3_connections = list_connections(
        client=client,
        connector=ConnectorType._S3,
        connection_type=ConnectionType.IMPORT
    )
    
    print("Available S3 Connections:")
    for conn in s3_connections:
        print(f"- ID: {conn.connection_id}")
    
    # List all GCS connections
    gcs_connections = list_connections(
        client=client,
        connector=ConnectorType._GCS
    )
    
    print("Available GCS Connections:")
    for conn in gcs_connections:
        print(f"- ID: {conn.connection_id}")
    
    # Delete a connection if needed
    # delete_response = delete_connection(client, connection_id="connection_id_here")
    # print(f"Connection deleted: {delete_response}")
    
except LabellerrError as e:
    print(f"Operation failed: {str(e)}")

Connection Testing Best PracticesAlways test your connection before creating datasets:

Explicit Path Testing (S3): Provide the exact S3 path you’ll use for data access
Implicit Validation (GCS): GCS connections validate both credentials and path accessibility
Error Handling: Wrap connection operations in try-except blocks
Credential Security: Never hardcode credentials; use environment variables or secret managers

Using Connections with Datasets

Once you’ve created and tested a cloud connection (S3 or GCS), you can use it to create datasets directly from your cloud storage. This allows you to manage large volumes of files without manual uploads, and keeps your data in sync with your existing cloud infrastructure.

Create Datasets from Cloud Storage

Learn how to create datasets using your S3 or GCS connections in our dedicated Create Datasets guide, including complete code examples and troubleshooting tips.

Localization & Data Residency

Region selection

Run workspaces and data in-country/region (e.g., India, EU) to keep traffic in-geo.

Data scope

Datasets, tool instances, and model-assisted labeling endpoints stay in the chosen region.

Latency

Pick the nearest region to reduce round trips for uploads, model calls, and labeling.

On-prem / private cloud

Available for strict residency or compliance needs—contact us to align on region and setup.

Frequently Asked Questions

How do I get my client_id?

Visit your workspace API keys page at https://<your-workspace-name>.labellerr.com/workspace/api-keys and click the Show Client ID button to reveal and copy your client ID.

Where can I find my API credentials?

You can obtain your api_key and api_secret by visiting: https://<your-workspace-name>.labellerr.com/workspace/api-keys

SDK Documentation

MCP Server

Getting Started

Introduction

Installation

Getting Started

Obtaining API Credentials

Initialize the Client

Understanding the SDK Structure

Example Client Initialization:

Common Import Patterns

Working with Cloud Connections

Creating and Testing Connections

Using Connections with Datasets

Create Datasets from Cloud Storage

Localization & Data Residency

Frequently Asked Questions

SDK Documentation

MCP Server

​Introduction

​Installation

​Getting Started

​Obtaining API Credentials

​Initialize the Client

​Understanding the SDK Structure

​Example Client Initialization:

​Common Import Patterns

​Working with Cloud Connections

​Creating and Testing Connections

​Using Connections with Datasets

Create Datasets from Cloud Storage

​Localization & Data Residency

​Frequently Asked Questions

Introduction

Installation

Getting Started

Obtaining API Credentials

Initialize the Client

Understanding the SDK Structure

Example Client Initialization:

Common Import Patterns

Working with Cloud Connections

Creating and Testing Connections

Using Connections with Datasets

Localization & Data Residency

Frequently Asked Questions