# BackendClient

Main client for interacting with the Synapse backend API.

## Overview[​](#overview "Overview에 대한 직접 링크")

The `BackendClient` provides comprehensive access to all backend operations including data management, plugin execution, annotations, and machine learning workflows. It aggregates functionality from multiple specialized mixins:

* **AnnotationClientMixin**: Task and annotation management
* **CoreClientMixin**: File upload and core operations
* **DataCollectionClientMixin**: Data collection and file management
* **HITLClientMixin**: Human-in-the-loop assignment operations
* **IntegrationClientMixin**: Plugin and job management
* **MLClientMixin**: Machine learning models and ground truth operations

## Constructor[​](#constructor "Constructor에 대한 직접 링크")

```python
BackendClient(
    base_url: str,
    access_token: str = None,
    *,
    authorization_token: str = None,
    tenant: str = None,
    agent_token: str = None,
    timeout: dict = None
)

```

### Parameters[​](#parameters "Parameters에 대한 직접 링크")

| Parameter             | Type   | Required | Default                      | Description                                          |
| --------------------- | ------ | -------- | ---------------------------- | ---------------------------------------------------- |
| `base_url`            | `str`  | Yes      | -                            | Base URL of the Synapse backend API                  |
| `access_token`        | `str`  | No       | `None`                       | API access token (or use `SYNAPSE_ACCESS_TOKEN` env) |
| `authorization_token` | `str`  | No       | `None`                       | Legacy authorization token (deprecated)              |
| `tenant`              | `str`  | No       | `None`                       | Tenant code for multi-tenant deployments             |
| `agent_token`         | `str`  | No       | `None`                       | Agent token for agent-initiated requests             |
| `timeout`             | `dict` | No       | `{'connect': 5, 'read': 15}` | Custom timeout settings                              |

### Example[​](#example "Example에 대한 직접 링크")

```python
from synapse_sdk.clients.backend import BackendClient

# Create client with explicit token
client = BackendClient(
    base_url="https://api.synapse.sh",
    access_token="your-access-token"
)

# Or use environment variables
import os
os.environ['SYNAPSE_ACCESS_TOKEN'] = "your-access-token"
client = BackendClient(base_url="https://api.synapse.sh")

```

## API Methods[​](#api-methods "API Methods에 대한 직접 링크")

### Annotation Operations[​](#annotation-operations "Annotation Operations에 대한 직접 링크")

#### `get_project(pk)`[​](#get_projectpk "get_projectpk에 대한 직접 링크")

Get project details by ID.

```python
project = client.get_project(123)

```

#### `get_task(pk, params)`[​](#get_taskpk-params "get_taskpk-params에 대한 직접 링크")

Get task details with optional parameters.

```python
task = client.get_task(456, params={'expand': 'data_unit'})

```

#### `annotate_task_data(pk, data)`[​](#annotate_task_datapk-data "annotate_task_datapk-data에 대한 직접 링크")

Submit annotation data for a task.

```python
result = client.annotate_task_data(456, {
    'annotations': [
        {'type': 'bbox', 'coordinates': [10, 10, 100, 100]}
    ]
})

```

#### `list_tasks(params=None, url_conversion=None, list_all=False)`[​](#list_tasksparamsnone-url_conversionnone-list_allfalse "list_tasksparamsnone-url_conversionnone-list_allfalse에 대한 직접 링크")

List tasks with filtering and pagination.

```python
# Get tasks for a project
tasks = client.list_tasks(params={'project': 123})

# Get all tasks (handles pagination automatically)
all_tasks = client.list_tasks(list_all=True)

```

#### `create_tasks(data)`[​](#create_tasksdata "create_tasksdata에 대한 직접 링크")

Create new tasks.

```python
new_tasks = client.create_tasks([
    {'project': 123, 'data_unit': 789},
    {'project': 123, 'data_unit': 790}
])

```

#### `set_tags_tasks(data, params=None)`[​](#set_tags_tasksdata-paramsnone "set_tags_tasksdata-paramsnone에 대한 직접 링크")

Set tags for multiple tasks.

```python
client.set_tags_tasks({
    'task_ids': [456, 457],
    'tag_ids': [1, 2, 3]
})

```

### Core Operations[​](#core-operations "Core Operations에 대한 직접 링크")

#### `create_chunked_upload(file_path)`[​](#create_chunked_uploadfile_path "create_chunked_uploadfile_path에 대한 직접 링크")

Upload large files using chunked upload for optimal performance.

```python
from pathlib import Path

result = client.create_chunked_upload(Path('/path/to/large_file.zip'))
print(f"Upload completed: {result}")

```

**Features:**

* Uses 50MB chunks for optimal performance
* Automatic retry and resume capability
* MD5 integrity verification
* Progress tracking support

### Data Collection Operations[​](#data-collection-operations "Data Collection Operations에 대한 직접 링크")

#### `list_data_collection()`[​](#list_data_collection "list_data_collection에 대한 직접 링크")

List all available data collections.

```python
collections = client.list_data_collection()

```

#### `get_data_collection(data_collection_id)`[​](#get_data_collectiondata_collection_id "get_data_collectiondata_collection_id에 대한 직접 링크")

Get detailed information about a specific data collection.

```python
collection = client.get_data_collection(123)
file_specs = collection['file_specifications']

```

#### `create_data_file(file_path, use_chunked_upload=False)`[​](#create_data_filefile_path-use_chunked_uploadfalse "create_data_filefile_path-use_chunked_uploadfalse에 대한 직접 링크")

Create and upload a data file to the backend.

```python
from pathlib import Path

# Regular upload
data_file = client.create_data_file(Path('/path/to/file.jpg'))

# Chunked upload for large files
large_file = client.create_data_file(
    Path('/path/to/large_file.zip'),
    use_chunked_upload=True
)

```

#### `upload_data_file(organized_file, collection_id, use_chunked_upload=False)`[​](#upload_data_fileorganized_file-collection_id-use_chunked_uploadfalse "upload_data_fileorganized_file-collection_id-use_chunked_uploadfalse에 대한 직접 링크")

Upload organized file data to a collection.

```python
result = client.upload_data_file(
    organized_file={'files': {...}, 'meta': {...}},
    collection_id=123,
    use_chunked_upload=False
)

```

#### `create_data_units(uploaded_files)`[​](#create_data_unitsuploaded_files "create_data_unitsuploaded_files에 대한 직접 링크")

Create data units from uploaded files.

```python
data_units = client.create_data_units([
    {'id': 1, 'file': {...}},
    {'id': 2, 'file': {...}}
])

```

### HITL (Human-in-the-Loop) Operations[​](#hitl-human-in-the-loop-operations "HITL (Human-in-the-Loop) Operations에 대한 직접 링크")

#### `get_assignment(pk)`[​](#get_assignmentpk "get_assignmentpk에 대한 직접 링크")

Get assignment details by ID.

```python
assignment = client.get_assignment(789)

```

#### `list_assignments(params=None, url_conversion=None, list_all=False)`[​](#list_assignmentsparamsnone-url_conversionnone-list_allfalse "list_assignmentsparamsnone-url_conversionnone-list_allfalse에 대한 직접 링크")

List assignments with filtering options.

```python
# Get assignments for a project
assignments = client.list_assignments(params={'project': 123})

# Get all assignments
all_assignments = client.list_assignments(list_all=True)

```

#### `set_tags_assignments(data, params=None)`[​](#set_tags_assignmentsdata-paramsnone "set_tags_assignmentsdata-paramsnone에 대한 직접 링크")

Set tags for multiple assignments.

```python
client.set_tags_assignments({
    'assignment_ids': [789, 790],
    'tag_ids': [1, 2]
})

```

### Integration Operations[​](#integration-operations "Integration Operations에 대한 직접 링크")

#### `health_check_agent(token)`[​](#health_check_agenttoken "health_check_agenttoken에 대한 직접 링크")

Check agent health status.

```python
status = client.health_check_agent('agent-token-123')

```

#### `get_plugin(pk)` / `create_plugin(data)` / `update_plugin(pk, data)`[​](#get_pluginpk--create_plugindata--update_pluginpk-data "get_pluginpk--create_plugindata--update_pluginpk-data에 대한 직접 링크")

Manage plugins.

```python
# Get plugin
plugin = client.get_plugin(123)

# Create plugin
new_plugin = client.create_plugin({
    'name': 'My Plugin',
    'description': 'Plugin description'
})

# Update plugin
updated = client.update_plugin(123, {'description': 'Updated description'})

```

#### `run_plugin(pk, data)`[​](#run_pluginpk-data "run_pluginpk-data에 대한 직접 링크")

Execute a plugin with provided data.

```python
result = client.run_plugin(123, {
    'parameters': {'input': 'value'},
    'context': {...}
})

```

#### Plugin Release Management[​](#plugin-release-management "Plugin Release Management에 대한 직접 링크")

```python
# Create plugin release
release = client.create_plugin_release({
    'plugin': 123,
    'version': '1.0.0',
    'file': open('/path/to/plugin.zip', 'rb')
})

# Get release details
release_info = client.get_plugin_release(456)

```

#### Job Management[​](#job-management "Job Management에 대한 직접 링크")

```python
# List jobs
jobs = client.list_jobs(params={'status': 'running'})

# Get job details
job = client.get_job(789, params={'expand': 'logs'})

# Update job status
client.update_job(789, {'status': 'completed'})

# Get job console logs
logs = client.list_job_console_logs(789)

```

#### Storage Operations[​](#storage-operations "Storage Operations에 대한 직접 링크")

```python
# List storages
storages = client.list_storages()

# Get storage details
storage = client.get_storage(123)

# Create storage
new_storage = client.create_storage({
    'name': 'My Storage',
    'provider': 'amazon_s3',
    'configuration': {...}
})

```

### Machine Learning Operations[​](#machine-learning-operations "Machine Learning Operations에 대한 직접 링크")

#### `list_models(params=None)` / `get_model(pk, params=None, url_conversion=None)`[​](#list_modelsparamsnone--get_modelpk-paramsnone-url_conversionnone "list_modelsparamsnone--get_modelpk-paramsnone-url_conversionnone에 대한 직접 링크")

Manage ML models.

```python
# List models
models = client.list_models(params={'project': 123})

# Get model details
model = client.get_model(456, params={'expand': 'metrics'})

```

#### `create_model(data)`[​](#create_modeldata "create_modeldata에 대한 직접 링크")

Create a new ML model with file upload.

```python
new_model = client.create_model({
    'name': 'My Model',
    'project': 123,
    'file': '/path/to/model.pkl'
})

```

#### Ground Truth Operations[​](#ground-truth-operations "Ground Truth Operations에 대한 직접 링크")

```python
# List ground truth events
events = client.list_ground_truth_events(
    params={'ground_truth_dataset_versions': [123]},
    list_all=True
)

# Get ground truth version
version = client.get_ground_truth_version(123)

```

## Storage Models[​](#storage-models "Storage Models에 대한 직접 링크")

The backend client includes predefined models for storage operations:

### StorageCategory[​](#storagecategory "StorageCategory에 대한 직접 링크")

* `INTERNAL`: Internal storage systems
* `EXTERNAL`: External storage providers

### StorageProvider[​](#storageprovider "StorageProvider에 대한 직접 링크")

* `AMAZON_S3`: Amazon S3
* `AZURE`: Microsoft Azure Blob Storage
* `DIGITAL_OCEAN`: DigitalOcean Spaces
* `FILE_SYSTEM`: Local file system
* `FTP` / `SFTP`: FTP protocols
* `MINIO`: MinIO storage
* `GCP`: Google Cloud Storage

## Error Handling[​](#error-handling "Error Handling에 대한 직접 링크")

All API methods may raise `ClientError` exceptions for various error conditions:

```python
from synapse_sdk.clients.exceptions import ClientError

try:
    project = client.get_project(999)
except ClientError as e:
    print(f"API Error: {e}")
    print(f"Status Code: {e.status_code}")
    print(f"Response: {e.response}")

```

## Pagination[​](#pagination "Pagination에 대한 직접 링크")

Methods supporting `list_all=True` will automatically handle pagination:

```python
# Manual pagination
tasks_page1 = client.list_tasks(params={'page': 1, 'page_size': 100})

# Automatic pagination (recommended)
all_tasks = client.list_tasks(list_all=True)

```

## URL Conversion[​](#url-conversion "URL Conversion에 대한 직접 링크")

Some methods support URL conversion for file fields:

```python
# Custom URL conversion
tasks = client.list_tasks(
    url_conversion={'files': lambda url: f"https://cdn.example.com{url}"}
)

```

## Related[​](#related "Related에 대한 직접 링크")

* [AgentClient](/ko/api/clients/agent.md) — For agent-specific operations
* [BaseClient](/ko/api/clients/base.md) — Base client implementation