Client

Client class for CVAT server connection and authentication

The Client class provides session management, authentication, and access to CVAT server APIs.

Creating a Client

Basic Initialization

from cvat_sdk import Client

client = Client(url="cvat.example.com")

The URL can be specified with or without a protocol:

• "cvat.example.com" - Auto-detects HTTPS/HTTP
• "https://cvat.example.com" - Explicit HTTPS
• "http://localhost:8080" - Explicit HTTP with port

Using make_client Helper

The make_client function provides a convenient way to create and authenticate a client:

from cvat_sdk import make_client

# With password authentication
client = make_client(
    host="cvat.example.com",
    credentials=("username", "password")
)

# With access token
client = make_client(
    host="cvat.example.com",
    access_token="your_personal_access_token"
)

# With custom port
client = make_client(
    host="cvat.example.com",
    port=8080,
    credentials=("username", "password")
)

Authentication

The SDK supports two authentication methods: password-based and token-based.

Password Authentication

Authenticate with username and password:

from cvat_sdk import Client, PasswordCredentials

client = Client(url="cvat.example.com")

# Using tuple
client.login(("username", "password"))

# Using PasswordCredentials class
credentials = PasswordCredentials(user="username", password="password")
client.login(credentials)

Token Authentication

Authenticate with a Personal Access Token (PAT):

from cvat_sdk import Client, AccessTokenCredentials

client = Client(url="cvat.example.com")

# Using AccessTokenCredentials class
credentials = AccessTokenCredentials(token="your_token_here")
client.login(credentials)

Token authentication is recommended for automation and CI/CD pipelines.

Checking Authentication Status

if client.has_credentials():
    print("Client is authenticated")
else:
    print("Client is not authenticated")

Logging Out

client.logout()

Configuration

Customize client behavior with the Config class:

from cvat_sdk import Client, Config

config = Config(
    status_check_period=5.0,  # Operation status check interval in seconds
    allow_unsupported_server=True,  # Allow unsupported server versions
    verify_ssl=True,  # Verify SSL certificates (or None for default)
    cache_dir="/custom/cache/path"  # Custom cache directory
)

client = Client(url="cvat.example.com", config=config)

Configuration Options

status_check_period · float · default: "5"

Interval in seconds between status checks for long-running operations (uploads, exports, etc.)

allow_unsupported_server · bool · default: "True"

Whether to allow connection to unsupported CVAT server versions. If False, raises IncompatibleVersionException.

verify_ssl · bool | None · default: "None"

SSL certificate verification. Set to False to disable (not recommended for production).

cache_dir · Path · default: "~/.cache/cvat-sdk"

Directory for caching server data (used by datasets and PyTorch adapters).

Context Manager

Use the client as a context manager for automatic cleanup:

with Client(url="cvat.example.com") as client:
    client.login(("username", "password"))
    # Perform operations
    tasks = client.tasks.list()
# Connection automatically closed

Manual cleanup:

client = Client(url="cvat.example.com")
try:
    client.login(("username", "password"))
    # Perform operations
finally:
    client.close()

API Access

The client provides access to various CVAT resources through repository properties:

Tasks Repository

# Access tasks repository
tasks_repo = client.tasks

# List all tasks
tasks = tasks_repo.list()

# Get specific task
task = tasks_repo.retrieve(123)

# Create task
task = tasks_repo.create(spec=task_spec)

Projects Repository

# Access projects repository
projects_repo = client.projects

projects = projects_repo.list()
project = projects_repo.retrieve(456)

Jobs Repository

# Access jobs repository
jobs_repo = client.jobs

jobs = jobs_repo.list()
job = jobs_repo.retrieve(789)

Users Repository

# Access users repository
users_repo = client.users

users = users_repo.list()
user = users_repo.retrieve(1)

Organizations Repository

# Access organizations repository
orgs_repo = client.organizations

orgs = orgs_repo.list()
org = orgs_repo.retrieve(10)

Issues and Comments

# Access issues
issues_repo = client.issues
issues = issues_repo.list()

# Access comments
comments_repo = client.comments
comments = comments_repo.list()

Organization Context

Set an organization context for all operations:

# Set organization context by slug
client.organization_slug = "my-organization"

# All operations now use this organization
tasks = client.tasks.list()  # Only tasks in 'my-organization'

# Clear organization context (use personal workspace)
client.organization_slug = None

# Temporarily use different organization
with client.organization_context("other-org"):
    tasks = client.tasks.list()  # Tasks in 'other-org'
# Reverts to previous context after block

Low-Level API Access

Access the underlying auto-generated API client:

from cvat_sdk.api_client import Configuration, ApiClient

# The client exposes the low-level API client
api_client = client.api_client

# Access specific API endpoints
server_api = api_client.server_api
about, response = server_api.retrieve_about()
print(f"Server version: {about.version}")

# Access configuration
api_config = api_client.configuration
print(f"Host: {api_config.host}")

Server Version Checking

The SDK checks server version compatibility on initialization:

# Disable version check during initialization
client = Client(url="cvat.example.com", check_server_version=False)

# Manually check version later
try:
    client.check_server_version(fail_if_unsupported=True)
except IncompatibleVersionException as e:
    print(f"Incompatible server version: {e}")

# Get server version
from packaging.version import Version
server_version: Version = client.get_server_version()
print(f"Server version: {server_version}")

Supported server versions are typically the current and next minor version relative to the SDK version.

Waiting for Long Operations

Some operations (uploads, exports) are asynchronous. Use wait_for_completion to wait for them:

# After starting an async operation that returns a request ID
rq_id = "some-request-id"

request, response = client.wait_for_completion(
    rq_id,
    status_check_period=3,  # Check every 3 seconds
    log_prefix="My operation"  # Custom log message prefix
)

print(f"Operation completed with status: {request.status}")

Logging

The client uses Python’s standard logging module:

import logging

# Create custom logger
logger = logging.getLogger("my_cvat_client")
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler()
handler.setFormatter(logging.Formatter('%(asctime)s - %(levelname)s - %(message)s'))
logger.addHandler(handler)

# Pass logger to client
client = Client(url="cvat.example.com", logger=logger)

# Access client's logger
client.logger.info("Custom log message")

API URL Construction

The client provides URL construction utilities:

# Access the API URL builder
api_map = client.api_map

# Get base URL
print(f"Host: {api_map.host}")  # e.g., "https://cvat.example.com"
print(f"API base: {api_map.base}")  # e.g., "https://cvat.example.com/api/"

# Build custom endpoint URL
url = api_map.make_endpoint_url(
    "/api/tasks/{id}/data",
    kwsub={"id": 123},
    query_params={"quality": "compressed"}
)

Exception Handling

from cvat_sdk.core.exceptions import (
    IncompatibleVersionException,
    InvalidHostException,
    BackgroundRequestException
)
from cvat_sdk.api_client.exceptions import ApiException

try:
    client = Client(url="invalid://url")
except InvalidHostException as e:
    print(f"Invalid host: {e}")

try:
    client.check_server_version(fail_if_unsupported=True)
except IncompatibleVersionException as e:
    print(f"Version mismatch: {e}")

try:
    task = client.tasks.retrieve(99999)
except ApiException as e:
    print(f"API error: {e.status} - {e.reason}")

Next Steps

• Core Operations - Working with projects, tasks, and jobs
• PyTorch Adapter - Use CVAT data for training
• Auto-Annotation - Automate annotations with models