Skip to main content
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

​
Getting Started

​
Obtaining API Credentials

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

Log in to Labellerr

Log in to your Labellerr account at https://login.labellerr.com/
2

Create your Workspace

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

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:
ProviderImport PermissionsExport Permissions
AWS S3s3:GetObject, s3:ListBucket, s3:GetBucketCors, s3:GetBucketLocation, s3:PutBucketCors+ s3:PutObject, s3:DeleteObject
GCSstorage.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
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.

​
Frequently Asked Questions

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