Client APIs

The Synapse SDK provides comprehensive client libraries for interacting with various backend services and systems. This section documents all available client APIs and their usage.

Overview

The client APIs are organized into several categories:

Core Clients

• BackendClient - Main client for Synapse backend operations (API v1)
• BackendClientV2 - Sync + async client for Synapse Backend API v2 (cursor pagination, resource-attribute surface, targets synapse-backend v2026.2.3)
• BaseClient - Base client with common functionality
• AgentClient - Agent-specific operations
• RayClient - Ray distributed computing integration
• PipelineServiceClient - Pipeline orchestration service

Backend Client Mixins

The BackendClient is composed of several specialized mixins that provide focused functionality:

• AnnotationClientMixin - Task and annotation management
• CoreClientMixin - Core file upload operations
• DataCollectionClientMixin - Data collection and file management
• HITLClientMixin - Human-in-the-loop workflows
• IntegrationClientMixin - Plugin and job management
• MLClientMixin - Machine learning operations

Quick Start

Basic Backend Client Usage

from synapse_sdk.clients.backend import BackendClient

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

# Use annotation operations
tasks = client.list_tasks(params={'project': 123})

# Use data collection operations
collections = client.list_data_collections()

# Use ML operations
models = client.list_models(params={'project': 123})

Environment Configuration

import os

# Set environment variables
os.environ['SYNAPSE_ACCESS_TOKEN'] = "your-access-token"
os.environ['SYNAPSE_AGENT_TOKEN'] = "your-agent-token"

# Client will automatically use environment variables
client = BackendClient(base_url="https://api.synapse.sh")

Authentication

All clients support multiple authentication methods:

Access Token Authentication

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

Environment Variable Authentication

# Set SYNAPSE_ACCESS_TOKEN environment variable
client = BackendClient(base_url="https://api.synapse.sh")

Agent Token Authentication (for agents)

client = BackendClient(
    base_url="https://api.synapse.sh",
    agent_token="your-agent-token"
)

Common Patterns

Error Handling

from synapse_sdk.clients.exceptions import ClientError

try:
    result = client.get_project(123)
except ClientError as e:
    if e.status_code == 404:
        print("Project not found")
    elif e.status_code == 403:
        print("Permission denied")
    else:
        print(f"API Error: {e}")

Pagination

# Manual pagination
page1 = client.list_tasks(params={'page': 1, 'page_size': 50})

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

Batch Operations

# Create multiple tasks
tasks_data = [
    {'project': 123, 'data_unit': 789},
    {'project': 123, 'data_unit': 790},
    {'project': 123, 'data_unit': 791}
]
created_tasks = client.create_tasks(tasks_data)

# Set tags for multiple assignments
client.set_tags_assignments({
    'ids': [1, 2, 3],
    'tags': [10, 11],
    'action': 'add'
})

File Operations

from pathlib import Path

# Upload large files with chunked upload
result = client.create_chunked_upload(Path('/path/to/large_file.zip'))

# Create data file
data_file = client.create_data_file(
    Path('/path/to/data.jpg'),
    use_chunked_upload=True
)

Client Capabilities by Use Case

Annotation Workflows

Use AnnotationClientMixin for:

• Managing annotation projects
• Creating and assigning tasks
• Submitting annotation data
• Task tagging and organization

Key Methods:

• list_tasks(), create_tasks(), annotate_task_data()
• get_project(), set_tags_tasks()

Data Management

Use DataCollectionClientMixin for:

• Managing data collections
• Uploading files and datasets
• Creating data units
• Batch data processing

Key Methods:

• list_data_collections(), get_data_collection()
• create_data_file(), upload_data_file()
• create_data_units()

Human-in-the-Loop

Use HITLClientMixin for:

• Managing human review assignments
• Quality control workflows
• Assignment distribution
• Performance analytics

Key Methods:

• list_assignments(), get_assignment()
• set_tags_assignments()

System Integration

Use IntegrationClientMixin for:

• Plugin development and management
• Job execution and monitoring
• Storage configuration
• Agent health monitoring

Key Methods:

• create_plugin(), run_plugin()
• list_jobs(), update_job()
• create_storage(), health_check_agent()

Machine Learning

Use MLClientMixin for:

• Model management and deployment
• Ground truth data operations
• Model evaluation workflows
• Training data preparation

Key Methods:

• create_model(), list_models()
• list_ground_truth_events(), get_ground_truth_version()

Core Operations

Use CoreClientMixin for:

• Large file uploads
• Chunked upload operations
• File integrity verification

Key Methods:

• create_chunked_upload()

Complete Workflow Examples

End-to-End Data Processing

def complete_data_workflow():
    client = BackendClient(
        base_url="https://api.synapse.sh",
        access_token="your-token"
    )

    # 1. Data ingestion
    collection = client.get_data_collection(123)
    data_file = client.create_data_file(Path('/data/image.jpg'))

    # 2. Task creation
    tasks = client.create_tasks([
        {'project': 123, 'data_unit': data_file['data_unit_id']}
    ])

    # 3. Assignment management
    assignments = client.list_assignments(params={'project': 123})

    # 4. Model operations
    models = client.list_models(params={'project': 123})

    return {
        'data_file': data_file,
        'tasks': tasks,
        'assignments': assignments,
        'models': models
    }

Plugin Development and Deployment

def plugin_deployment_workflow():
    client = BackendClient(
        base_url="https://api.synapse.sh",
        access_token="your-token"
    )

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

    # 2. Create release
    with open('plugin.zip', 'rb') as f:
        release = client.create_plugin_release({
            'plugin': plugin['id'],
            'version': '1.0.0',
            'file': f
        })

    # 3. Execute plugin
    job = client.run_plugin(plugin['id'], {
        'parameters': {'threshold': 0.8}
    })

    # 4. Monitor execution
    job_status = client.get_job(job['job_id'])

    return {
        'plugin': plugin,
        'release': release,
        'job': job_status
    }

Best Practices

Performance Optimization

• Use list_all=True for complete datasets to handle pagination automatically
• Use chunked upload for files larger than 50MB
• Implement retry logic for critical operations
• Use batch operations when available

Error Handling

• Always wrap API calls in try-catch blocks
• Check for specific error codes (404, 403, 429, 500)
• Implement exponential backoff for rate limiting
• Log errors with sufficient context

Resource Management

• Close file handles promptly
• Use context managers for file operations
• Monitor memory usage with large uploads
• Clean up temporary resources

Security

• Store API tokens securely (environment variables)
• Use HTTPS endpoints only
• Validate file paths and inputs
• Implement proper access controls

Migration Guide

When migrating from older SDK versions:

1. Update imports: New mixin structure may require import updates
2. Check method signatures: Some methods may have updated parameters
3. Error handling: Error types and status codes may have changed
4. Configuration: Authentication methods may have been enhanced

Migrating to Synapse Backend API v2

For new call sites that target the v2 backend (/v2/*), use BackendClientV2 instead of BackendClient. The two clients coexist; migrate incrementally.

Key differences:

• Cursor pagination (next/previous/results, no count) — per_page= instead of page_size=.
• Auth headers: SYNAPSE-ACCESS-TOKEN: syn_<token> and a raw SYNAPSE-Tenant: <code> (no Token prefix by default; pass tenant_token_prefix=True for legacy parity).
• Resource surface: client.projects.list(...) instead of client.list_projects(...).
• Typed Pydantic models for both requests (*V2CreateRequest) and responses (*V2List / *V2Detail).

See the BackendClientV2 migration table for a per-concern v1 ↔ v2 mapping.

Troubleshooting

Common Issues

Authentication Errors (401/403)

• Verify API token is correct and not expired
• Check token permissions for the requested operations
• Ensure correct base URL

Rate Limiting (429)

• Implement exponential backoff
• Reduce request frequency
• Use batch operations when available

File Upload Failures

• Check file size limits
• Verify file permissions
• Use chunked upload for large files
• Check network connectivity

Connection Timeouts

• Increase timeout settings
• Check network stability
• Verify server availability

Support

For additional support:

• Check the troubleshooting guide
• Review plugin examples
• Consult the FAQ