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

# Migration Guide

> Migrate to Avala from other annotation platforms

This guide covers how to migrate your annotation data and workflows from other platforms to Avala. Whether you're coming from CVAT, Labelbox, Label Studio, or another tool, Avala supports importing data in common annotation formats.

## Overview

Migrating to Avala generally follows three steps:

1. **Export** your data and annotations from your current platform
2. **Transform** the exported data into an Avala-compatible format if needed
3. **Import** the data into Avala via the API or Mission Control

<Tip>
  Need help with a large or complex migration? Contact us at **[support@avala.ai](mailto:support@avala.ai)** for assisted migration support. Our team can help with custom format conversions, bulk imports, and data validation.
</Tip>

***

## Migrating from CVAT

[CVAT](https://www.cvat.ai/) supports exporting annotations in several formats that Avala can import directly.

### Step 1: Export from CVAT

1. Open your CVAT project or task
2. Click **Export task dataset** (or **Export project dataset**)
3. Select one of these formats:
   * **COCO 1.0** (recommended for image annotations)
   * **CVAT for images 1.1** (XML format)
   * **YOLO 1.1** (for bounding box annotations)
4. Download the exported archive

### Step 2: Import to Avala

Upload your images to an Avala dataset using presigned URLs, then import the annotations using the REST API. For file upload details, see the [REST API guide](/docs/sdks/rest-api#file-uploads).

```bash theme={null}
# Import COCO annotations
curl -X POST "https://api.avala.ai/api/v1/datasets/{owner}/{slug}/import/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "coco", "file_url": "https://your-storage/annotations.json"}'
```

<Info>
  The SDK supports read operations (list, get) and exports (create). For dataset creation, uploads, and annotation import, use the REST API directly.
</Info>

### Label Mapping

CVAT labels map directly to Avala labels. If your CVAT project uses attributes, they will be imported as annotation attributes in Avala.

| CVAT Concept | Avala Equivalent     |
| ------------ | -------------------- |
| Task         | Project              |
| Job          | Work Batch           |
| Label        | Label                |
| Attribute    | Annotation Attribute |
| Track        | Tracking Annotation  |
| Tag          | Classification Label |

***

## Migrating from Labelbox

[Labelbox](https://labelbox.com/) exports annotations in its native JSON format or COCO format.

### Step 1: Export from Labelbox

1. Navigate to your Labelbox project
2. Go to **Export** and select **Export v2**
3. Choose your export format:
   * **Labelbox JSON** (native format with all metadata)
   * **COCO** (recommended for Avala import)
4. Download the export file

### Step 2: Transform and Import

If exporting in COCO format, you can import directly via the REST API. For Labelbox JSON format, convert to COCO first:

```bash theme={null}
# Import COCO annotations via the REST API
curl -X POST "https://api.avala.ai/api/v1/datasets/{owner}/{slug}/import/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "coco", "file_url": "https://your-storage/annotations.json"}'
```

### Label Mapping

| Labelbox Concept    | Avala Equivalent        |
| ------------------- | ----------------------- |
| Project             | Project                 |
| Data Row            | Dataset Item            |
| Label               | Annotation              |
| Tool (Bounding Box) | Bounding Box Annotation |
| Tool (Polygon)      | Polygon Annotation      |
| Tool (Polyline)     | Polyline Annotation     |
| Tool (Point)        | Keypoint Annotation     |
| Classification      | Classification Label    |
| Benchmark           | Consensus               |
| Review              | Review                  |

***

## Migrating from Label Studio

[Label Studio](https://labelstud.io/) supports multiple export formats including COCO, YOLO, and its own JSON format.

### Step 1: Export from Label Studio

1. Open your Label Studio project
2. Click **Export** in the top navigation
3. Select your format:
   * **COCO** (recommended for object detection annotations)
   * **YOLO** (for bounding box annotations)
   * **JSON** (Label Studio native format)
4. Download the export

### Step 2: Import to Avala

```bash theme={null}
# Import COCO annotations from Label Studio export
curl -X POST "https://api.avala.ai/api/v1/datasets/{owner}/{slug}/import/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "coco", "file_url": "https://your-storage/annotations.json"}'
```

### Label Mapping

| Label Studio Concept | Avala Equivalent     |
| -------------------- | -------------------- |
| Project              | Project              |
| Task                 | Dataset Item         |
| Annotation           | Annotation           |
| RectangleLabels      | Bounding Box         |
| PolygonLabels        | Polygon              |
| KeyPointLabels       | Keypoint             |
| BrushLabels          | Segmentation         |
| Choices              | Classification Label |

***

## Migrating from Scale AI

[Scale AI](https://scale.com/) provides annotation services and exports data in its native JSON format or standard formats.

### Step 1: Export from Scale AI

1. Navigate to your Scale AI project dashboard
2. Go to **Tasks** and select **Export**
3. Choose your export format:
   * **Scale JSON** (native format with all task metadata)
   * **COCO** (recommended for Avala import)
4. Download the export archive

<Warning>
  Scale AI exports include task metadata (instructions, parameters, callback URLs) that do not carry over. Only annotation geometry and labels are imported into Avala.
</Warning>

### Step 2: Transform and Import

If exporting in COCO format, import directly. For Scale JSON format, convert the annotation geometry to COCO first.

**Scale JSON annotations** use a `response` object per task with annotation arrays. Key fields to map:

```json theme={null}
{
  "response": {
    "annotations": [
      {
        "label": "car",
        "type": "bounding_box",
        "left": 100, "top": 200, "width": 300, "height": 150
      }
    ]
  }
}
```

Convert to COCO format, then import:

```bash theme={null}
curl -X POST "https://api.avala.ai/api/v1/datasets/{owner}/{slug}/import/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "coco", "file_url": "https://your-storage/annotations.json"}'
```

### Label Mapping

| Scale AI Concept           | Avala Equivalent        |
| -------------------------- | ----------------------- |
| Project                    | Project                 |
| Task                       | Dataset Item            |
| Annotation (bounding\_box) | Bounding Box Annotation |
| Annotation (polygon)       | Polygon Annotation      |
| Annotation (line)          | Polyline Annotation     |
| Annotation (point)         | Keypoint Annotation     |
| Annotation (cuboid)        | 3D Cuboid Annotation    |
| Category                   | Label                   |
| Audit                      | Review                  |

### Scale AI-Specific Notes

* **3D annotations**: Scale AI's LiDAR cuboid annotations include heading and velocity fields. Heading maps to Avala's yaw rotation; velocity is stored as annotation metadata.
* **Consensus tasks**: Scale AI's audit/review results do not have a direct mapping. Import them as separate annotation versions and use Avala's consensus feature for comparison.
* **Image groups**: Scale AI's image group tasks should be split into individual items when importing to Avala.

***

## Migrating from Encord

[Encord](https://encord.com/) (formerly Cord) exports annotations in its native JSON format or COCO format.

### Step 1: Export from Encord

1. Open your Encord project
2. Navigate to **Labels** → **Export**
3. Choose your export format:
   * **Encord JSON** (native format, includes all metadata)
   * **COCO** (recommended for Avala import)
4. Download the export

### Step 2: Transform and Import

For COCO exports, import directly via the REST API:

```bash theme={null}
curl -X POST "https://api.avala.ai/api/v1/datasets/{owner}/{slug}/import/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "coco", "file_url": "https://your-storage/annotations.json"}'
```

For Encord JSON exports, the annotation structure uses `objects` and `classifications` arrays per frame:

```json theme={null}
{
  "data_units": {
    "image_hash": {
      "labels": {
        "objects": [
          {
            "name": "car",
            "shape": "bounding_box",
            "value": "car",
            "boundingBox": {"x": 0.1, "y": 0.2, "w": 0.3, "h": 0.15}
          }
        ],
        "classifications": [
          { "name": "weather", "value": "sunny" }
        ]
      }
    }
  }
}
```

<Warning>
  Encord uses **normalized coordinates** (0.0-1.0 relative to image dimensions). Convert to absolute pixel coordinates before importing to Avala's COCO format.
</Warning>

### Label Mapping

| Encord Concept         | Avala Equivalent        |
| ---------------------- | ----------------------- |
| Project                | Project                 |
| Data Unit              | Dataset Item            |
| Object (bounding\_box) | Bounding Box Annotation |
| Object (polygon)       | Polygon Annotation      |
| Object (polyline)      | Polyline Annotation     |
| Object (point)         | Keypoint Annotation     |
| Classification         | Classification Label    |
| Ontology               | Label Taxonomy          |
| Label Row              | Annotation Set          |
| Review                 | Review                  |

### Encord-Specific Notes

* **Ontology structure**: Encord's hierarchical ontology (nested classifications under objects) maps to Avala's label taxonomy with nested attributes. Review the mapping to ensure nested classification groups transfer correctly.
* **Video annotations**: Encord stores video annotations per-frame with object tracking IDs. Map tracking IDs to Avala's tracking annotation feature.
* **Priority queues**: Encord's labeling priority queues do not transfer. Recreate prioritization using Avala's [work batches](/docs/annotation/guides/work-batches).

***

## General Migration Steps

For platforms not listed above, follow this general process:

### 1. Export Your Data

Export annotations from your current platform in a standard format. Most platforms support at least one of these:

* COCO JSON
* YOLO TXT
* Pascal VOC XML

### 2. Transform to Avala Format

If your export format is not directly supported, transform it to COCO format, which provides the most complete mapping to Avala's annotation model.

### 3. Upload Data to Avala

Create a dataset and upload your images or data files using the REST API. File uploads use presigned URLs — see the [REST API guide](/docs/sdks/rest-api#file-uploads) for details.

```bash theme={null}
# Create a dataset via the REST API
curl -X POST "https://api.avala.ai/api/v1/datasets/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "migrated-data", "data_type": "image"}'
```

<Info>
  The SDK supports read operations (`client.datasets.list()`, `client.datasets.get(uid)`) and exports (`client.exports.create()`). For dataset creation, uploads, and annotation imports, use the REST API directly.
</Info>

### 4. Import Annotations

Import the exported annotations into your Avala dataset:

```bash theme={null}
curl -X POST "https://api.avala.ai/api/v1/datasets/{owner}/{slug}/import/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format": "coco", "file_url": "https://your-storage/annotations.json"}'
```

### 5. Verify and Review

After import, verify your data using the SDK or Mission Control:

```python theme={null}
from avala import Client

client = Client()

# List datasets to find your imported data
page = client.datasets.list()
for dataset in page:
    print(f"{dataset.name} ({dataset.uid})")
```

***

## Data Format Mapping

The following table shows how common annotation formats map to Avala's internal format.

| Source Format         | Annotation Types Supported                                      | Notes                                                                          |
| --------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| **COCO JSON**         | Bounding boxes, polygons, keypoints, segmentation masks         | Recommended format. Full metadata support including categories and image info. |
| **YOLO TXT**          | Bounding boxes                                                  | One text file per image. Class IDs mapped via a separate classes file.         |
| **Pascal VOC XML**    | Bounding boxes                                                  | One XML file per image. Supports difficulty flags and truncation metadata.     |
| **CVAT XML**          | Bounding boxes, polygons, polylines, keypoints, tracks          | Preserves tracking information and frame-level annotations.                    |
| **Labelbox JSON**     | All types                                                       | Requires conversion to COCO for import. Contact support for assistance.        |
| **Label Studio JSON** | All types                                                       | Requires conversion to COCO for import.                                        |
| **Scale AI JSON**     | Bounding boxes, polygons, polylines, keypoints, cuboids         | Convert `response.annotations` to COCO. Heading/velocity stored as metadata.   |
| **Encord JSON**       | Bounding boxes, polygons, polylines, keypoints, classifications | Convert normalized coordinates to absolute pixels, then to COCO.               |

***

## Tips for a Smooth Migration

* **Start with a small test**: Migrate a small subset of your data first to validate the process before migrating everything.
* **Verify label consistency**: Ensure label names match between your source platform and Avala. Mismatched labels will be created as new labels.
* **Preserve metadata**: When possible, export with full metadata to retain information like creation dates, annotator assignments, and review statuses.
* **Back up your source data**: Keep a copy of your exported data from the original platform until you have verified the migration is complete.

<Tip>
  For enterprise migrations involving large datasets (100,000+ items) or custom formats, contact **[support@avala.ai](mailto:support@avala.ai)** for dedicated migration assistance.
</Tip>