Skip to main content

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:

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: