Python, sync and async

The Python package mirrors the public /v1 namespaces with Pydantic models, safe retries, cursor pages, and synchronous or asynchronous clients.

The Python client requires Python 3.12 or newer and currently ships as verified wheel and source-distribution artifacts with each GitHub release, not from PyPI. Install synapse-spec and synapse-client from the same version bundle.

Install

# Download both matching artifacts from the release.
python -m pip install ./synapse_spec-0.1.0-py3-none-any.whl \
  ./synapse_client-0.1.0-py3-none-any.whl

Start a subject journey

import os
import uuid
from synapse_client import SynapseClient

request_id = str(uuid.uuid4())  # persist this with the workflow

with SynapseClient(
    os.environ["SYNAPSE_API_URL"],
    api_key=os.environ["SYNAPSE_ENVIRONMENT_KEY"],
) as synapse:
    subject, _created = synapse.subjects.upsert(
        organization_id,
        app_id,
        environment_id,
        external_id=authenticated_user_id,
        profile={"locale": "en"},
        idempotency_key=f"{request_id}:subject",
    )
    synapse.programs.enroll(
        organization_id,
        app_id,
        environment_id,
        subject_id=subject.id,
        program_id=program_id,
        idempotency_key=f"{request_id}:enrollment",
    )
    session = synapse.participant_sessions.create(
        organization_id,
        app_id,
        environment_id,
        program_id=program_id,
        subject_id=subject.id,
        expires_in_seconds=3600,
        idempotency_key=f"{request_id}:session",
    )
    print(session.hosted_url)

expires_in_seconds defaults to one hour and accepts 300 seconds up to ten years (315360000). Resending the same launch with a new idempotency key while its session is still open returns that session and extends expires_at to at least expires_in_seconds from now; only the expiry may differ, and it is never shortened.

Async applications

from synapse_client import AsyncSynapseClient

async with AsyncSynapseClient(base_url, api_key=environment_key) as synapse:
    page = await synapse.evaluations.list(
        organization_id,
        app_id,
        environment_id,
        limit=50,
    )
    for evaluation in page.items:
        print(evaluation.id, evaluation.status)

Contract notes

SynapseClient and AsyncSynapseClient expose matching namespaces and models.
ApiError exposes status, detail, request_id, retry_after, and response headers.
Use list_all_* helpers when you explicitly want to consume every cursor page.
Pass a persisted opaque idempotency_key for every mutation.