Client

client

Kaleidoscope API Client Module.

This module provides the main client class for interacting with the Kaleidoscope API.

The KaleidoscopeClient provides access to various service endpoints including:

• activities: Manage activities
• imports: Import data into Kaleidoscope
• programs: Manage programs
• entity_types: Manage entity types
• records: Manage records
• fields: Manage fields
• experiments: Manage experiments
• record_views: Manage record views
• exports: Export data from Kaleidoscope

Attributes:

Name	Type	Description
PROD_API_URL	str	The production URL for the Kaleidoscope API.
TIMEOUT_MAXIMUM	int	Maximum timeout for API requests in seconds.

Example

    # instantiate client object
    client = KaleidoscopeClient(
        client_id="your_client_id",
        client_secret="your_client_secret"
    )

    # retrieve activities
    programs = client.activities.get_activities()

PROD_API_URL module-attribute

PROD_API_URL = 'https://api.kaleidoscope.bio'

The production URL for the Kaleidoscope API.

This is the default url used for the KaleidoscopeClient, in the event no url is provided in the KaleidoscopeClient's initialization

TIMEOUT_MAXIMUM module-attribute

TIMEOUT_MAXIMUM = 300

Maximum timeout for API requests in seconds.

KalbioAPIError

KalbioAPIError(method: str, url: str, status_code: int, response_body: Any)

Bases: Exception

Raised when a Kaleidoscope API request returns a 4xx or 5xx response.

Attributes:

Name	Type	Description
method		HTTP method of the failed request (e.g. "PUT").
url		Relative endpoint path (e.g. "/activity_definitions/abc").
status_code		HTTP status code returned by the server.
response_body		Raw response body. Usually a Kaleidoscope structured error (JSON with code/message or Zod validation details); occasionally bytes/HTML for unexpected failures.

Source code in kalbio/client.py

def __init__(
    self,
    method: str,
    url: str,
    status_code: int,
    response_body: Any,
):
    self.method = method
    self.url = url
    self.status_code = status_code
    self.response_body = response_body
    if isinstance(response_body, bytes):
        body_str = response_body.decode("utf-8", errors="replace")
    else:
        body_str = str(response_body)
    super().__init__(
        f"{method} {url} failed with status {status_code}: {body_str}"
    )

KaleidoscopeClient

KaleidoscopeClient(client_id: str | None = _env_client_id, client_secret: str | None = _env_client_secret, url: str = PROD_API_URL, additional_headers: dict = {}, iap_client_id: str | None = None, verify_ssl: bool = True)

A client for interacting with the Kaleidoscope API.

This client provides a high-level interface to various Kaleidoscope services including imports, programs, entity types, records, fields, tasks, experiments, record views, and exports. It handles authentication using API key credentials and provides methods for making HTTP requests (GET, POST, PUT) to the API endpoints.

Attributes:

Name	Type	Description
activities	ActivitiesService	Service for managing activities.
dashboards	DashboardsService	Service for managing dashboards.
workspace	WorkspaceService	Service for workspace-related operations.
programs	ProgramsService	Service for managing programs.
labels	LabelsService	Service for managing labels.
entity_types	EntityTypesService	Service for managing entity types.
entity_fields	EntityFieldsService	Service for managing entity fields.
records	RecordsService	Service for managing records.
record_views	RecordViewsService	Service for managing record views.
imports	ImportsService	Service for managing data imports.
exports	ExportsService	Service for managing data exports.
property_fields	PropertyFieldsService	Service for managing property fields.

Example

client = KaleidoscopeClient(
    client_id="your_api_client_id",
    client_secret="your_api_client_secret"
)
# Use the client to interact with various services
programs = client.activities.get_activities()

# For applications behind Google Cloud IAP:
client = KaleidoscopeClient(
    client_id="your_api_client_id",
    client_secret="your_api_client_secret",
    iap_client_id="your_iap_client_id.apps.googleusercontent.com"
)

Sets up the client with API credentials and optional API URL, and initializes service interfaces for interacting with different API endpoints.

Parameters:

Name	Type	Description	Default
client_id	str	The API client ID for authentication.	_env_client_id
client_secret	str	The API client secret for authentication.	_env_client_secret
url	str | None	The base URL for the API. Defaults to the production API URL if not provided.	PROD_API_URL
iap_client_id	str | None	The OAuth client ID for Google Cloud Identity-Aware Proxy. If provided, the client will automatically fetch and refresh IAP tokens. Requires the google-auth package.	None

Example

# Using explicit credentials
client = KaleidoscopeClient(client_id="id", client_secret="secret")

# Or rely on environment variables KALEIDOSCOPE_API_CLIENT_ID/SECRET
client = KaleidoscopeClient()

# For applications behind Google Cloud IAP
client = KaleidoscopeClient(
    client_id="id",
    client_secret="secret",
    iap_client_id="your_iap_client_id.apps.googleusercontent.com"
)

Source code in kalbio/client.py

def __init__(
    self,
    client_id: Optional[str] = _env_client_id,
    client_secret: Optional[str] = _env_client_secret,
    url: str = PROD_API_URL,
    additional_headers: dict = {},
    iap_client_id: Optional[str] = None,
    verify_ssl: bool = True,
):
    """Initialize the Kaleidoscope API client.

    Sets up the client with API credentials and optional API URL, and initializes
    service interfaces for interacting with different API endpoints.

    Args:
        client_id (str): The API client ID for authentication.
        client_secret (str): The API client secret for authentication.
        url (Optional[str]): The base URL for the API. Defaults to the production
            API URL if not provided.
        iap_client_id (Optional[str]): The OAuth client ID for Google Cloud
            Identity-Aware Proxy. If provided, the client will automatically
            fetch and refresh IAP tokens. Requires the `google-auth` package.

    Example:
        ```python
        # Using explicit credentials
        client = KaleidoscopeClient(client_id="id", client_secret="secret")

        # Or rely on environment variables KALEIDOSCOPE_API_CLIENT_ID/SECRET
        client = KaleidoscopeClient()

        # For applications behind Google Cloud IAP
        client = KaleidoscopeClient(
            client_id="id",
            client_secret="secret",
            iap_client_id="your_iap_client_id.apps.googleusercontent.com"
        )
        ```
    """
    if client_id is None:
        raise ValueError(
            'No client_id provided and "KALEIDOSCOPE_API_CLIENT_ID" was not found in the environment.'
        )

    if client_secret is None:
        raise ValueError(
            'No client_secret provided and "KALEIDOSCOPE_API_CLIENT_SECRET" was not found in the environment.'
        )

    from kalbio.activities import ActivitiesService
    from kalbio.dashboards import DashboardsService
    from kalbio.entity_fields import EntityFieldsService
    from kalbio.entity_types import EntityTypesService
    from kalbio.exports import ExportsService
    from kalbio.files import FilesService
    from kalbio.imports import ImportsService
    from kalbio.labels import LabelsService
    from kalbio.programs import ProgramsService
    from kalbio.property_fields import PropertyFieldsService
    from kalbio.record_views import RecordViewsService
    from kalbio.records import RecordsService
    from kalbio.registration import RegistrationService
    from kalbio.result_table_templates import ResultTableTemplatesService
    from kalbio.workspace import WorkspaceService

    self._api_url = url

    self.activities = ActivitiesService(self)
    self.dashboards = DashboardsService(self)
    self.entity_fields = EntityFieldsService(self)
    self.entity_types = EntityTypesService(self)
    self.exports = ExportsService(self)
    self.files = FilesService(self)
    self.imports = ImportsService(self)
    self.labels = LabelsService(self)
    self.property_fields = PropertyFieldsService(self)
    self.programs = ProgramsService(self)
    self.record_views = RecordViewsService(self)
    self.records = RecordsService(self)
    self.registration = RegistrationService(self)
    self.result_table_templates = ResultTableTemplatesService(self)
    self.workspace = WorkspaceService(self)

    self._client_id = client_id
    self._client_secret = client_secret
    self.additional_headers = additional_headers
    self._iap_client_id = iap_client_id
    self._verify_ssl = verify_ssl