> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labellerr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Learn how to install and initialize the Labellerr SDK, a Python library for seamless interaction with the Labellerr platform to manage data annotations, projects, and exports.

<Note>
  **New version v2.0.0 of the SDK is available** with major improvements and new features. See the [Changelog](/sdk/changelog) for details and upgrade notes.
</Note>

## 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:

<CodeBlock lang="bash" title="Install Labellerr SDK">
  pip install git+[https://github.com/Labellerr/SDKPython.git](https://github.com/Labellerr/SDKPython.git)
</CodeBlock>

## Getting Started

### Obtaining API Credentials

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

<Steps>
  <Step title="Log in to Labellerr">
    Log in to your Labellerr account at [https://login.labellerr.com/](https://login.labellerr.com/)
  </Step>

  <Step title="Create your Workspace">
    Create a new workspace or access your existing workspace from the dashboard.
  </Step>

  <Step title="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
  </Step>
</Steps>

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

### 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:

```python Client Initialization theme={"dark"}
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:

```python Import Examples for Common Tasks theme={"dark"}
# 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.

<Warning>
  **Required Permissions**

  Before 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:

  * [AWS S3 Permissions Guide](/getting-started/connect-aws-s3)
  * [GCS Permissions Guide](/getting-started/connect-gcs)
</Warning>

### Creating and Testing Connections

<Tabs>
  <Tab title="AWS S3 Connection">
    <Info>
      **S3 Connection with Explicit Path Testing**

      For 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.
    </Info>

    ```python Create and Test S3 Connection theme={"dark"}
    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)}")
    ```

    <Note>
      **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
    </Note>
  </Tab>

  <Tab title="GCS Connection">
    <Info>
      **GCS Connection with Service Account**

      For Google Cloud Storage, you need to provide a service account JSON file. The connection test validates both credentials and path access.
    </Info>

    ```python Create and Test GCS Connection theme={"dark"}
    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)}")
    ```

    <Note>
      **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
    </Note>
  </Tab>

  <Tab title="List & Manage Connections">
    ```python List and Manage Connections theme={"dark"}
    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)}")
    ```
  </Tab>
</Tabs>

<Warning>
  **Connection Testing Best Practices**

  Always 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
</Warning>

***

## 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.

<Card title="Create Datasets from Cloud Storage" icon="database" href="/sdk/create-dataset-sdk#method-2-create-dataset-with-aws-s3-connection">
  Learn how to create datasets using your S3 or GCS connections in our dedicated **Create Datasets** guide, including complete code examples and troubleshooting tips.
</Card>

***

## Localization & Data Residency

<AccordionGroup>
  <Accordion title="Region selection" icon="globe">
    Run workspaces and data in-country/region (e.g., India, EU) to keep traffic in-geo.
  </Accordion>

  <Accordion title="Data scope" icon="shield">
    Datasets, tool instances, and model-assisted labeling endpoints stay in the chosen region.
  </Accordion>

  <Accordion title="Latency" icon="bolt">
    Pick the nearest region to reduce round trips for uploads, model calls, and labeling.
  </Accordion>

  <Accordion title="On-prem / private cloud" icon="server">
    Available for strict residency or compliance needs—contact us to align on region and setup.
  </Accordion>
</AccordionGroup>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>