### Install Encord Python API Client

Source: https://github.com/encord-team/encord-client-python/blob/master/README.md

Install the Encord Python API Client using pip. Ensure you are using Python 3.9 or later.

```bash
python3 -m pip install encord
```

--------------------------------

### Retrieve a dataset by hash using EncordUserClient

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Fetch a specific dataset using its unique hash with `get_dataset`. This allows access to dataset properties and its data rows. The example iterates through data rows, printing their UID, hash, and title.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
dataset = client.get_dataset("ds-hash-uuid")

print(dataset.title)
for data_row in dataset.data_rows:
    print(data_row.uid, data_row.data_hash, data_row.data_title)
```

--------------------------------

### Export Labels to COCO Format

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Exports labels from a project in COCO format. Requires the 'coco' extra to be installed (`pip install encord[coco]`).

```python
from encord import EncordUserClient
import json

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")

coco_data = project.export_coco_labels(branch_name="main")

with open("coco_annotations.json", "w") as f:
    json.dump(coco_data, f, indent=2)

print(f"Exported {len(coco_data['annotations'])} annotations")
```

--------------------------------

### Project.export_coco_labels

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Exports labels from a project in COCO format. Requires the 'coco' extra to be installed.

```APIDOC
## Project.export_coco_labels — Export labels in COCO format

Requires the `coco` extra: `pip install encord[coco]`.

### Description
Exports labels from a project in COCO format.

### Method
`project.export_coco_labels(branch_name: str)`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **branch_name** (str) - Required - The name of the branch to export labels from.

### Request Example
```python
from encord import EncordUserClient
import json

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")

coco_data = project.export_coco_labels(branch_name="main")

with open("coco_annotations.json", "w") as f:
    json.dump(coco_data, f, indent=2)

print(f"Exported {len(coco_data['annotations'])} annotations")
```

### Response
#### Success Response (200)
- **coco_data** (dict) - A dictionary containing the exported labels in COCO format.

#### Response Example
```json
{
  "annotations": [
    {
      "id": 1,
      "image_id": 100,
      "category_id": 1,
      "bbox": [100, 200, 400, 300],
      "area": 120000,
      "iscrowd": 0,
      "segmentation": []
    }
  ],
  "images": [
    {
      "id": 100,
      "width": 1920,
      "height": 1080,
      "file_name": "image1.jpg"
    }
  ],
  "categories": [
    {
      "id": 1,
      "name": "car",
      "supercategory": "object"
    }
  ]
}
```
```

--------------------------------

### Retrieve editor activity logs

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Use `get_editor_logs` to retrieve logs of user activity within the Encord editor. You can specify a start and end time for the log retrieval.

```python
from encord import EncordUserClient
from datetime import datetime, timedelta

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")

end = datetime.now()
start = end - timedelta(days=1)

for log in project.get_editor_logs(start_time=start, end_time=end):
    print(log.action, log.actor_user_email, log.created_at)
```

--------------------------------

### Query collaborator time-on-task

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Use `list_time_spent` to query the time collaborators have spent on tasks within a project. Requires a start date and optionally a user email for filtering.

```python
from encord import EncordUserClient
from datetime import datetime, timedelta

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")

start = datetime.now() - timedelta(days=7)
for entry in project.list_time_spent(start=start, user_email="annotator@example.com"):
    print(entry.user_email, entry.duration_seconds, entry.date)
```

--------------------------------

### Create New Project

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Create a new project with specified title, description, dataset hashes, ontology hash, and workflow settings. Omitting the ontology hash creates a blank ontology.

```python
from encord import EncordUserClient
from encord.orm.project import ManualReviewWorkflowSettings

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

project_hash = client.create_project(
    project_title="Traffic Sign Detection",
    dataset_hashes=["ds-hash-1", "ds-hash-2"],
    project_description="Annotate traffic signs for autonomous driving",
    ontology_hash="onto-hash-abc",  # omit to create a blank ontology
    workflow_settings=ManualReviewWorkflowSettings(),
)
print(f"Created project: {project_hash}")
```

--------------------------------

### EncordUserClient.create_project

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Create a new project.

```APIDOC
## EncordUserClient.create_project

### Description
Create a new project.

### Method
`EncordUserClient.create_project`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from encord import EncordUserClient
from encord.orm.project import ManualReviewWorkflowSettings

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

project_hash = client.create_project(
    project_title="Traffic Sign Detection",
    dataset_hashes=["ds-hash-1", "ds-hash-2"],
    project_description="Annotate traffic signs for autonomous driving",
    ontology_hash="onto-hash-abc",  # omit to create a blank ontology
    workflow_settings=ManualReviewWorkflowSettings(),
)
print(f"Created project: {project_hash}")
```

### Response
#### Success Response
The hash of the newly created project.

#### Response Example
```
a1b2c3d4-0000-0000-0000-000000000000
```
```

--------------------------------

### Create a new dataset with EncordUserClient

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Use `create_dataset` to initialize a new dataset. Specify the title, type (e.g., `CORD_STORAGE`), description, and whether to create a backing folder. The dataset hash is returned upon successful creation.

```python
from encord import EncordUserClient
from encord.orm.dataset import StorageLocation

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

result = client.create_dataset(
    dataset_title="Dashcam Footage Q1",
    dataset_type=StorageLocation.CORD_STORAGE,
    dataset_description="Front-facing dashcam, January–March",
    create_backing_folder=True,   # mirrors dataset in Storage
)
print(result.dataset_hash)  # "ds-uuid-..."
```

--------------------------------

### Initialize Encord User Client with SSH Private Key

Source: https://github.com/encord-team/encord-client-python/blob/master/README.md

Authenticate with Encord by initializing the User Client using the path to your SSH private key. Replace '<private_key_path>' with the actual path to your key file.

```python
from encord import EncordUserClient

user_client = EncordUserClient.create_with_ssh_private_key(
  ssh_private_key_path="<private_key_path>"
  )
```

--------------------------------

### Project.create_bundle

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Batches multiple SDK operations into fewer network calls using a context manager.

```APIDOC
## Project.create_bundle — Batch multiple SDK operations into fewer network calls

### Description
The `Bundle` context manager collects operations and executes them in batches, significantly reducing API round-trips for bulk workflows.

### Method
`project.create_bundle(bundle_size: int)`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **bundle_size** (int) - Optional - The maximum number of operations to include in a single batch. Defaults to a suitable size if not specified.

### Request Example
```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")

label_rows = project.list_label_rows_v2()

# Initialise 200 label rows in ~4 network calls instead of 200
with project.create_bundle(bundle_size=50) as bundle:
    for row in label_rows:
        row.initialise_labels(bundle=bundle)

# Save many label rows in bulk
with project.create_bundle() as bundle:
    for row in label_rows:
        if row.is_labelling_initialised:
            row.save(bundle=bundle)

print(f"Processed {len(label_rows)} rows")
```

### Response
#### Success Response (200)
Indicates that the batched operations have been processed. No specific return object is detailed.

#### Response Example
```
Processed 200 rows
```
```

--------------------------------

### Retrieve Project by Hash

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Fetch a Project instance using its unique hash. This instance provides access to project metadata, ontology, label rows, and workflow. Requires specific user roles.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project(project_hash="a1b2c3d4-0000-0000-0000-000000000000")

print(project.title)               # "My Detection Project"
print(project.project_hash)        # "a1b2c3d4-ứt"
print(project.ontology_structure)  # OntologyStructure(objects=[...], classifications=[...])
print(project.created_at)          # datetime(...)
```

--------------------------------

### Download label data using LabelRowV2.initialise_labels

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Call `initialise_labels` on a `LabelRowV2` object to download its associated label data before reading or writing annotations. This can be done individually or in bulk using a `Bundle` for efficiency.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")
label_rows = project.list_label_rows_v2()

# Initialise individually
label_row = label_rows[0]
label_row.initialise_labels()

# Initialise in bulk using Bundle (reduces network round-trips)
with project.create_bundle() as bundle:
    for row in label_rows:
        row.initialise_labels(bundle=bundle)

print(f"Initialised {len(label_rows)} rows")
```

--------------------------------

### Create a storage folder

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Use `create_storage_folder` to create a new folder in your Encord storage. You can provide a name, description, and client metadata.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

folder = client.create_storage_folder(
    name="Dashcam Q2 2024",
    description="Raw video captures",
    client_metadata={"source": "fleet-A", "region": "EU"},
)
print(folder.uuid)
```

--------------------------------

### List label rows with filters using Project.list_label_rows_v2

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Retrieve label rows from a project using `list_label_rows_v2`. This method supports various filters including status, branch, and date ranges. Ensure the client is initialized before use.

```python
from encord import EncordUserClient
from encord.orm.label_row import AnnotationTaskStatus

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")

# All label rows
all_rows = project.list_label_rows_v2()

# Only queued rows on a feature branch
pending = project.list_label_rows_v2(
    label_statuses=[AnnotationTaskStatus.QUEUED],
    branch_name="v2-annotations",
    include_client_metadata=True,
)

for row in pending:
    print(row.data_title, row.label_hash, row.annotation_task_status)
```

--------------------------------

### EncordUserClient.get_project

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Retrieve a project by hash. Fetches a `Project` instance that exposes all project metadata, the ontology structure, label rows, workflow, and analytics.

```APIDOC
## EncordUserClient.get_project

### Description
Retrieve a project by hash. Fetches a `Project` instance that exposes all project metadata, the ontology structure, label rows, workflow, and analytics. Requires Project Admin, Team Manager, or Org Admin access.

### Method
`EncordUserClient.get_project`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project(project_hash="a1b2c3d4-0000-0000-0000-000000000000")

print(project.title)               # "My Detection Project"
print(project.project_hash)        # "a1b2c3d4-..."
print(project.ontology_structure)  # OntologyStructure(objects=[...], classifications=[...])
print(project.created_at)          # datetime(...)
```

### Response
#### Success Response
A `Project` instance.

#### Response Example
```
Project(...)
```
```

--------------------------------

### Create a data collection

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Create a new data collection within a specified top-level folder using `create_collection`. You can provide a name and description for the collection.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

collection = client.create_collection(
    top_level_folder_uuid="folder-uuid",
    name="Hard Negatives",
    description="Edge-case frames for model fine-tuning",
)
print(collection.uuid)
```

--------------------------------

### Batch SDK Operations with Bundles

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Batches multiple SDK operations into fewer network calls using the `Bundle` context manager. Useful for bulk workflows to reduce API round-trips.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")

label_rows = project.list_label_rows_v2()

# Initialise 200 label rows in ~4 network calls instead of 200
with project.create_bundle(bundle_size=50) as bundle:
    for row in label_rows:
        row.initialise_labels(bundle=bundle)

# Save many label rows in bulk
with project.create_bundle() as bundle:
    for row in label_rows:
        if row.is_labelling_initialised:
            row.save(bundle=bundle)

print(f"Processed {len(label_rows)} rows")
```

--------------------------------

### Authenticate with Bearer Token

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Create an authenticated client using a bearer token. Replace "<your-bearer-token>" with your actual token.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_bearer_token(token="<your-bearer-token>")
```

--------------------------------

### Create and upload annotations using LabelRowV2.add_object_instance and save

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Add `ObjectInstance` objects to a label row and then persist them to Encord using `save`. Annotations can be bounding boxes, polygons, etc., and can be set for specific frames with confidence scores.

```python
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.coordinates import BoundingBoxCoordinates, PolygonCoordinates

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")
label_rows = project.list_label_rows_v2()

label_row = label_rows[0]
label_row.initialise_labels()

# Retrieve the "Car" object class from the ontology
car_object = project.ontology_structure.get_child_by_title("Car")

# Create a bounding-box annotation on frame 0
car_instance = ObjectInstance(car_object)
car_instance.set_for_frames(
    BoundingBoxCoordinates(top_left_x=0.1, top_left_y=0.2, width=0.3, height=0.25),
    frames=0,
    confidence=0.95,
    manual_annotation=True,
)
label_row.add_object_instance(car_instance)

# Also annotate frame 5 with a polygon
car_frame5 = ObjectInstance(car_object)
car_frame5.set_for_frames(
    PolygonCoordinates(values=[{"x": 0.1, "y": 0.1}, {"x": 0.4, "y": 0.1},
                               {"x": 0.4, "y": 0.4}, {"x": 0.1, "y": 0.4}]),
    frames=5,
)
label_row.add_object_instance(car_frame5)

# Upload to Encord
label_row.save()
print(f"Saved label row: {label_row.label_hash}")
```

--------------------------------

### EncordUserClient.create_project_from_cvat

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Migrates a CVAT project to Encord by creating a new Encord project from CVAT export files.

```APIDOC
## EncordUserClient.create_project_from_cvat — Migrate a CVAT project to Encord

### Description
Migrates a CVAT project to Encord by creating a new Encord project from CVAT export files.

### Method
`client.create_project_from_cvat(import_method: LocalImport, dataset_name: str, review_mode: ReviewMode, transform_bounding_boxes_to_polygons: bool, timeout_seconds: int)`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **import_method** (LocalImport) - Required - Specifies the local path to the CVAT export files.
- **dataset_name** (str) - Required - The name for the new Encord dataset.
- **review_mode** (ReviewMode) - Required - The review mode for the project (e.g., `ReviewMode.LABELLED`).
- **transform_bounding_boxes_to_polygons** (bool) - Required - Whether to transform bounding boxes to polygons.
- **timeout_seconds** (int) - Optional - The timeout in seconds for the operation.

### Request Example
```python
from encord import EncordUserClient
from encord.utilities.client_utilities import LocalImport
from encord.orm.project import ReviewMode

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

result = client.create_project_from_cvat(
    import_method=LocalImport(file_path="/path/to/cvat_export/"),
    dataset_name="CVAT Migrated Dataset",
    review_mode=ReviewMode.LABELLED,
    transform_bounding_boxes_to_polygons=False,
    timeout_seconds=3600,
)

if hasattr(result, "project_hash"):
    print(f"Success! Project: {result.project_hash}, Dataset: {result.dataset_hash}")
    if result.issues.errors:
        print("Warnings:", result.issues.errors)
else:
    print("Import failed:", result.issues)
```

### Response
#### Success Response (200)
- **result** (object) - An object containing `project_hash`, `dataset_hash`, and `issues`.

#### Response Example
```
Success! Project: project-hash-uuid, Dataset: dataset-hash-uuid
```

#### Error Response
- **result** (object) - An object containing `issues` detailing the failure.

#### Error Response Example
```
Import failed: Issues(errors=['Error message'], warnings=[])
```
```

--------------------------------

### EncordUserClient.create_dataset

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Creates a new dataset in Encord. You can specify the title, type (e.g., CORD_STORAGE), description, and whether to create a backing folder.

```APIDOC
## EncordUserClient.create_dataset

### Description
Creates a new dataset in Encord.

### Method
`client.create_dataset()`

### Parameters
- **dataset_title** (str) - Required - The title for the new dataset.
- **dataset_type** (StorageLocation) - Required - The type of storage for the dataset (e.g., `StorageLocation.CORD_STORAGE`).
- **dataset_description** (str) - Optional - A description for the dataset.
- **create_backing_folder** (bool) - Optional - If True, mirrors the dataset in storage.

### Request Example
```python
from encord import EncordUserClient
from encord.orm.dataset import StorageLocation

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

result = client.create_dataset(
    dataset_title="Dashcam Footage Q1",
    dataset_type=StorageLocation.CORD_STORAGE,
    dataset_description="Front-facing dashcam, January–March",
    create_backing_folder=True,
)
print(result.dataset_hash)
```

### Response
#### Success Response
Returns a dataset object with a `dataset_hash`.
```

--------------------------------

### EncordUserClient.create_with_ssh_private_key

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Authenticate with an SSH private key. The key can be supplied as a string, a file path, or via environment variables.

```APIDOC
## EncordUserClient.create_with_ssh_private_key

### Description
Authenticate with an SSH private key. The key can be supplied as a string, a file path, or via the `ENCORD_SSH_KEY` / `ENCORD_SSH_KEY_FILE` environment variables.

### Method
`EncordUserClient.create_with_ssh_private_key`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from encord import EncordUserClient

# From a file path
client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="~/.ssh/encord_private_key"
)

# From an environment variable (no arguments needed when ENCORD_SSH_KEY is set)
import os
os.environ["ENCORD_SSH_KEY"] = open("~/.ssh/encord_private_key").read()
client = EncordUserClient.create_with_ssh_private_key()

# US or private cloud deployment
client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="~/.ssh/encord_private_key",
    domain="https://api.us.encord.com",
)
print(client)  # EncordUserClient instance ready to use
```

### Response
#### Success Response
An `EncordUserClient` instance.

#### Response Example
```
EncordUserClient(...)
```
```

--------------------------------

### LabelRowV2.initialise_labels

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Downloads label data from the server for a specific label row. This must be called before reading or writing annotations. Supports batched calls using `Bundle`.

```APIDOC
## LabelRowV2.initialise_labels

### Description
Downloads label data from the server. Must be called before reading or writing annotations.

### Method
`label_row.initialise_labels(bundle=None)`

### Parameters
- **bundle** (Bundle) - Optional - Use a `Bundle` object for batched network calls.

### Request Example
```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")
label_rows = project.list_label_rows_v2()

# Initialise individually
label_row = label_rows[0]
label_row.initialise_labels()

# Initialise in bulk using Bundle (reduces network round-trips)
with project.create_bundle() as bundle:
    for row in label_rows:
        row.initialise_labels(bundle=bundle)

print(f"Initialised {len(label_rows)} rows")
```

### Response
#### Success Response
Initializes the label data for the specified label row(s).
```

--------------------------------

### Create a New Ontology with Structure

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Creates a new ontology for a project, defining its title, description, and structure, including object classes with specified names and shapes. Returns the created ontology object.

```python
from encord import EncordUserClient
from encord.objects.ontology_structure import OntologyStructure
from encord.objects.common import Shape
from encord.objects.classification import Classification

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

structure = OntologyStructure()
# Add an object class
structure.add_object(name="Pedestrian", shape=Shape.BOUNDING_BOX)
structure.add_object(name="Vehicle", shape=Shape.POLYGON)

ontology = client.create_ontology(
    title="Street Scene v1",
    description="Objects for autonomous-driving annotation",
    structure=structure,
)
print(ontology.ontology_hash)
```

--------------------------------

### List top-level storage folders

Source: https://context7.com/encord-team/encord-client-python/llms.txt

List storage folders with optional filtering by search query and sorting. `list_storage_folders` allows specifying `order`, `desc`, and `page_size` for pagination and ordering.

```python
from encord import EncordUserClient
from encord.storage import FoldersSortBy

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

for folder in client.list_storage_folders(
    search="dashcam",
    order=FoldersSortBy.NAME,
    desc=False,
    page_size=50,
):
    print(folder.name, folder.uuid)
```

--------------------------------

### List and Filter Projects

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Iterate over Project objects, with options to filter by title, creation date, and organization-wide access. Requires Org Admin privileges for organization-wide access.

```python
from encord import EncordUserClient
from datetime import datetime, timedelta

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

# List all projects
for project in client.list_projects():
    print(project.title, project.project_hash)

# Filter by title and date
recent = list(client.list_projects(
    title_like="%detection%",
    created_after=datetime.now() - timedelta(days=30),
))
print(f"Found {len(recent)} recent detection projects")

# Org-wide access (must be Org Admin)
all_org = list(client.list_projects(include_org_access=True))
```

--------------------------------

### Authenticate with SSH Private Key

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Create an authenticated client using an SSH private key. The key can be provided as a file path or an environment variable. Supports custom domains for private cloud deployments.

```python
from encord import EncordUserClient

# From a file path
client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="~/.ssh/encord_private_key"
)

# From an environment variable (no arguments needed when ENCORD_SSH_KEY is set)
import os
os.environ["ENCORD_SSH_KEY"] = open("~/.ssh/encord_private_key").read()
client = EncordUserClient.create_with_ssh_private_key()

# US or private cloud deployment
client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="~/.ssh/encord_private_key",
    domain="https://api.us.encord.com",
)
print(client)  # EncordUserClient instance ready to use
```

--------------------------------

### Project.workflow

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Accesses and manages the project workflow, providing access to stages.

```APIDOC
## Project.workflow

### Description
Accesses and manages the project workflow, providing access to stages. This attribute is only available for workflow projects.

### Method
```python
workflow
```

### Parameters
None

### Request Example
```python
# Only available for workflow projects
workflow = project.workflow
for stage in workflow.stages:
    print(stage.title, stage.stage_type)
```

### Response
#### Success Response (200)
Returns a `Workflow` object.

#### Response Example
```python
# Example iteration over workflow stages
for stage in workflow.stages:
    print(stage.title, stage.stage_type)
```
```

--------------------------------

### Migrate CVAT Project to Encord

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Creates a new Encord project by migrating a CVAT project from a local export. Allows configuration of review mode and bounding box to polygon transformation.

```python
from encord import EncordUserClient
from encord.utilities.client_utilities import LocalImport
from encord.orm.project import ReviewMode

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

result = client.create_project_from_cvat(
    import_method=LocalImport(file_path="/path/to/cvat_export/"),
    dataset_name="CVAT Migrated Dataset",
    review_mode=ReviewMode.LABELLED,
    transform_bounding_boxes_to_polygons=False,
    timeout_seconds=3600,
)

if hasattr(result, "project_hash"):
    print(f"Success! Project: {result.project_hash}, Dataset: {result.dataset_hash}")
    if result.issues.errors:
        print("Warnings:", result.issues.errors)
else:
    print("Import failed:", result.issues)
```

--------------------------------

### List datasets with filters using EncordUserClient

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Use `get_datasets` to retrieve a list of datasets, optionally filtering by title patterns. The result includes the dataset object and the user's role for that dataset.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

datasets = client.get_datasets(title_like="%dashcam%")
for entry in datasets:
    ds = entry["dataset"]
    role = entry["user_role"]
    print(ds.title, ds.dataset_hash, role)
```

--------------------------------

### EncordUserClient.create_storage_folder

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Create a new storage folder within your Encord project. Folders help organize your uploaded media assets.

```APIDOC
## EncordUserClient.create_storage_folder

### Description
Create a new storage folder within your Encord project. Folders help organize your uploaded media assets.

### Method
```python
client.create_storage_folder(name: str, description: str = None, client_metadata: dict = None)
```

### Parameters
#### Query Parameters
- **name** (str) - Required - The name of the storage folder.
- **description** (str) - Optional - A description for the storage folder.
- **client_metadata** (dict) - Optional - Custom metadata to associate with the folder.

### Example
```python
folder = client.create_storage_folder(
    name="Dashcam Q2 2024",
    description="Raw video captures",
    client_metadata={"source": "fleet-A", "region": "EU"},
)
print(folder.uuid)
```
```

--------------------------------

### EncordUserClient.create_collection

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Create a new data collection within a specified top-level storage folder. Collections help group related data items.

```APIDOC
## EncordUserClient.create_collection

### Description
Create a new data collection within a specified top-level storage folder. Collections help group related data items.

### Method
```python
client.create_collection(top_level_folder_uuid: str, name: str, description: str = None)
```

### Parameters
#### Query Parameters
- **top_level_folder_uuid** (str) - Required - The UUID of the top-level storage folder to associate the collection with.
- **name** (str) - Required - The name of the data collection.
- **description** (str) - Optional - A description for the data collection.

### Example
```python
collection = client.create_collection(
    top_level_folder_uuid="folder-uuid",
    name="Hard Negatives",
    description="Edge-case frames for model fine-tuning",
)
print(collection.uuid)
```
```

--------------------------------

### Upload media to a storage folder

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Upload images or videos to a specific storage folder using `upload_image` or `upload_video`. Requires the folder's UUID and the local file path.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
folder = client.get_storage_folder("folder-uuid")

# Upload a single image
item = folder.upload_image("./frame_001.jpg", title="frame_001")
print(item.uuid, item.item_type)

# Upload a video
video_item = folder.upload_video("./clip_001.mp4", title="clip_001")
```

--------------------------------

### Import COCO Annotations into Project

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Imports COCO annotations into an Encord project. Requires mapping COCO category IDs to Encord feature hashes and COCO image IDs to Encord frame indices.

```python
from encord import EncordUserClient
from encord.utilities.coco.datastructure import FrameIndex
import json

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")

with open("coco_annotations.json") as f:
    coco = json.load(f)

# Map COCO category IDs to Encord feature hashes
category_to_hash = {1: "feature-hash-car", 2: "feature-hash-person"}

# Map COCO image IDs to (data_hash, frame_offset) pairs
image_to_frame = {
    100: FrameIndex(data_hash="data-hash-abc", frame=0),
    101: FrameIndex(data_hash="data-hash-def", frame=0),
}

project.import_coco_labels(
    labels_dict=coco,
    category_id_to_feature_hash=category_to_hash,
    image_id_to_frame_index=image_to_frame,
    branch_name="coco-import",
)
print("Import complete")
```

--------------------------------

### Retrieve storage items

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Fetch single or multiple storage items using their UUIDs. `get_storage_item` retrieves one item, while `get_storage_items` retrieves a list. The `sign_url` parameter controls whether signed URLs are generated.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

# Single item
item = client.get_storage_item("item-uuid", sign_url=True)
print(item.name, item.item_type, item.get_signed_url())

# Bulk retrieval
items = client.get_storage_items(
    item_uuids=["uuid-1", "uuid-2", "uuid-3"],
    sign_url=False,
)
for it in items:
    print(it.uuid, it.name)
```

--------------------------------

### LabelRowV2.workflow_complete / LabelRowV2.workflow_reopen / LabelRowV2.set_priority

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Manages the workflow state of label rows, including completing, reopening, and setting priority.

```APIDOC
## LabelRowV2.workflow_complete / LabelRowV2.workflow_reopen / LabelRowV2.set_priority

### Description
Manages the workflow state of label rows, including completing, reopening, and setting priority. `set_priority` is only available for workflow projects.

### Method
```python
workflow_complete(bundle: Bundle = None)
workflow_reopen()
set_priority(priority: float)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Complete multiple rows in one bundle
with project.create_bundle() as bundle:
    for row in label_rows[:10]:
        row.workflow_complete(bundle=bundle)

# Reopen a single row for re-annotation
label_rows[0].workflow_reopen()

# Set priority (workflow projects only)
label_rows[0].set_priority(priority=0.9)
```

### Response
#### Success Response (200)
Successfully updates the workflow state or priority of the label row(s).

#### Response Example
None provided in source.
```

--------------------------------

### LabelRowV2.add_object_instance and LabelRowV2.save

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Allows creation and uploading of annotations. You can add `ObjectInstance` objects with various coordinate types (e.g., BoundingBox, Polygon) and then save them to Encord.

```APIDOC
## LabelRowV2.add_object_instance + LabelRowV2.save

### Description
Create and upload annotations to a label row.

### Method
`label_row.add_object_instance(object_instance)`
`label_row.save()`

### Parameters
- **object_instance** (ObjectInstance) - Required - An `ObjectInstance` object with coordinates and class information.

### Request Example
```python
from encord import EncordUserClient
from encord.objects import ObjectInstance
from encord.objects.coordinates import BoundingBoxCoordinates, PolygonCoordinates

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")
label_rows = project.list_label_rows_v2()

label_row = label_rows[0]
label_row.initialise_labels()

# Retrieve the "Car" object class from the ontology
car_object = project.ontology_structure.get_child_by_title("Car")

# Create a bounding-box annotation on frame 0
car_instance = ObjectInstance(car_object)
car_instance.set_for_frames(
    BoundingBoxCoordinates(top_left_x=0.1, top_left_y=0.2, width=0.3, height=0.25),
    frames=0,
    confidence=0.95,
    manual_annotation=True,
)
label_row.add_object_instance(car_instance)

# Also annotate frame 5 with a polygon
car_frame5 = ObjectInstance(car_object)
car_frame5.set_for_frames(
    PolygonCoordinates(values=[{"x": 0.1, "y": 0.1}, {"x": 0.4, "y": 0.1},
                               {"x": 0.4, "y": 0.4}, {"x": 0.1, "y": 0.4}]),
    frames=5,
)
label_row.add_object_instance(car_frame5)

# Upload to Encord
label_row.save()
print(f"Saved label row: {label_row.label_hash}")
```

### Response
#### Success Response
Saves the annotations for the label row and returns the `label_hash`.
```

--------------------------------

### EncordUserClient.create_with_bearer_token

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Authenticate with a bearer token.

```APIDOC
## EncordUserClient.create_with_bearer_token

### Description
Authenticate with a bearer token.

### Method
`EncordUserClient.create_with_bearer_token`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from encord import EncordUserClient

client = EncordUserClient.create_with_bearer_token(token="<your-bearer-token>")
```

### Response
#### Success Response
An `EncordUserClient` instance.

#### Response Example
```
EncordUserClient(...)
```
```

--------------------------------

### EncordUserClient.create_ontology

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Creates a new ontology with a specified structure, including objects and classifications.

```APIDOC
## EncordUserClient.create_ontology

### Description
Creates a new ontology with a specified structure, including objects and classifications.

### Method
```python
create_ontology(title: str, description: str, structure: OntologyStructure)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
structure = OntologyStructure()
# Add an object class
structure.add_object(name="Pedestrian", shape=Shape.BOUNDING_BOX)
structure.add_object(name="Vehicle", shape=Shape.POLYGON)

ontology = client.create_ontology(
    title="Street Scene v1",
    description="Objects for autonomous-driving annotation",
    structure=structure,
)
print(ontology.ontology_hash)
```

### Response
#### Success Response (200)
Returns the created `Ontology` object, including its hash.

#### Response Example
```python
# Example output format
# print(ontology.ontology_hash)
```
```

--------------------------------

### EncordUserClient.get_datasets

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Lists datasets associated with the user, with support for filtering. You can filter datasets by title patterns.

```APIDOC
## EncordUserClient.get_datasets

### Description
Lists datasets with optional filters.

### Method
`client.get_datasets(title_like=None)`

### Parameters
- **title_like** (str) - Optional - A pattern to filter datasets by title (e.g., "%dashcam%").

### Request Example
```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

datasets = client.get_datasets(title_like="%dashcam%")
for entry in datasets:
    ds = entry["dataset"]
    role = entry["user_role"]
    print(ds.title, ds.dataset_hash, role)
```

### Response
#### Success Response
Returns a list of dictionaries, where each dictionary contains a `dataset` object and the `user_role`.
```

--------------------------------

### Project.get_task_actions

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Retrieve workflow task lifecycle events for a project. This includes actions like submission, approval, and rejection, along with associated metadata.

```APIDOC
## Project.get_task_actions

### Description
Retrieve workflow task lifecycle events for a project. This includes actions like submission, approval, and rejection, along with associated metadata.

### Method
```python
project.get_task_actions(after: datetime, action_type: list[TaskActionType] = None, actor_email: str = None)
```

### Parameters
#### Query Parameters
- **after** (datetime) - Required - Retrieve actions that occurred after this timestamp.
- **action_type** (list[TaskActionType]) - Optional - Filter by specific task action types (e.g., SUBMIT, APPROVE).
- **actor_email** (str) - Optional - Filter by the email of the user who performed the action.

### Example
```python
after = datetime.now() - timedelta(days=7)

for action in project.get_task_actions(
    after=after,
    action_type=[TaskActionType.SUBMIT, TaskActionType.APPROVE],
    actor_email="reviewer@example.com",
):
    print(action.action_type, action.actor_email, action.created_at)
```
```

--------------------------------

### Project.get_editor_logs

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Retrieve editor activity logs for a project. These logs capture user interactions within the Encord editor, such as actions performed and timestamps.

```APIDOC
## Project.get_editor_logs

### Description
Retrieve editor activity logs for a project. These logs capture user interactions within the Encord editor, such as actions performed and timestamps.

### Method
```python
project.get_editor_logs(start_time: datetime, end_time: datetime)
```

### Parameters
#### Query Parameters
- **start_time** (datetime) - Required - The start of the time range for log retrieval.
- **end_time** (datetime) - Required - The end of the time range for log retrieval.

### Example
```python
end = datetime.now()
start = end - timedelta(days=1)

for log in project.get_editor_logs(start_time=start, end_time=end):
    print(log.action, log.actor_user_email, log.created_at)
```
```

--------------------------------

### EncordUserClient.list_projects

Source: https://context7.com/encord-team/encord-client-python/llms.txt

List and filter projects. Returns an iterable of `Project` objects. Supports exact/fuzzy title filtering, date ranges, organisation-wide access, and tag filtering.

```APIDOC
## EncordUserClient.list_projects

### Description
List and filter projects. Returns an iterable of `Project` objects. Supports exact/fuzzy title filtering, date ranges, organisation-wide access, and tag filtering.

### Method
`EncordUserClient.list_projects`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **title_like** (str) - Optional - Filter projects by title (exact or fuzzy match).
- **created_after** (datetime) - Optional - Filter projects created after a specific date.
- **include_org_access** (bool) - Optional - Include projects with organization-wide access.

#### Request Body
None

### Request Example
```python
from encord import EncordUserClient
from datetime import datetime, timedelta

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")

# List all projects
for project in client.list_projects():
    print(project.title, project.project_hash)

# Filter by title and date
recent = list(client.list_projects(
    title_like="%detection%",
    created_after=datetime.now() - timedelta(days=30),
))
print(f"Found {len(recent)} recent detection projects")

# Org-wide access (must be Org Admin)
all_org = list(client.list_projects(include_org_access=True))
```

### Response
#### Success Response
An iterable of `Project` objects.

#### Response Example
```
[Project(...), Project(...)]
```
```

--------------------------------

### Read existing annotations using LabelRowV2.get_object_instances

Source: https://context7.com/encord-team/encord-client-python/llms.txt

Retrieve all object instances from an initialized label row using `get_object_instances`. This method is useful for inspecting or processing existing annotations.

```python
from encord import EncordUserClient

client = EncordUserClient.create_with_ssh_private_key(ssh_private_key_path="~/.ssh/key")
project = client.get_project("project-hash-uuid")
label_row = project.list_label_rows_v2()[0]
label_row.initialise_labels()

car_object = project.ontology_structure.get_child_by_title("Car")

# All instances
all_instances = label_row.get_object_instances()


```

--------------------------------

### EncordUserClient.list_storage_folders

Source: https://context7.com/encord-team/encord-client-python/llms.txt

List top-level storage folders within your Encord project. You can filter, sort, and paginate the results.

```APIDOC
## EncordUserClient.list_storage_folders

### Description
List top-level storage folders within your Encord project. You can filter, sort, and paginate the results.

### Method
```python
client.list_storage_folders(search: str = None, order: FoldersSortBy = None, desc: bool = False, page_size: int = 50)
```

### Parameters
#### Query Parameters
- **search** (str) - Optional - A search query to filter folders by name.
- **order** (FoldersSortBy) - Optional - The field to sort the folders by (e.g., NAME).
- **desc** (bool) - Optional - If True, sort in descending order.
- **page_size** (int) - Optional - The number of folders to return per page.

### Example
```python
for folder in client.list_storage_folders(
    search="dashcam",
    order=FoldersSortBy.NAME,
    desc=False,
    page_size=50,
):
    print(folder.name, folder.uuid)
```
```