base

Base HTTP client for the YouSleep API.

AsyncClient

Async HTTP client for the YouSleep API.

Provides type-safe methods for all API endpoints with automatic error handling, authentication, and retry logic.

Example

# Initialize with token
client = AsyncClient(
    base_url="https://api.yousleep.ai",
    token="your-jwt-token"
)

# Use as context manager (recommended)
async with AsyncClient(base_url="...", token="...") as client:
    projects = await client.projects.list()

# Or authenticate with credentials
from yousleep_common.models import UserAuthentication

credentials = UserAuthentication(
    email="user@example.com",
    password="password"
)
client = await AsyncClient.from_credentials(
    base_url="https://api.yousleep.ai",
    credentials=credentials
)

admin cached property

Access admin-related endpoints (requires admin role).

analyses cached property

Access analysis-related endpoints.

auth cached property

Access authentication-related endpoints.

batch cached property

Access batch operation endpoints.

billing cached property

Access billing and payment endpoints.

legal cached property

Access legal document and license endpoints.

organizations cached property

Access organization, membership and invitation endpoints.

projects cached property

Access project-related endpoints.

recordings cached property

Access recording-related endpoints.

report_exports cached property

Access report export creation, polling and history endpoints.

reports cached property

Access report generation endpoints.

status cached property

Access status-related endpoints.

studies cached property

Access study-related endpoints.

user cached property

Access user-related endpoints.

workflows cached property

Access high-level end-to-end analysis workflows.

__aenter__() async

Enter async context manager.

__aexit__(exc_type, exc_val, exc_tb) async

Exit async context manager.

__init__(base_url, token=None, refresh_token=None, api_key=None, timeout=30.0, max_retries=3, verify_connection=True, strict_version_check=True)

Initialize the async client.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL of the API (e.g., "https://api.yousleep.ai")	required
token	str | None	JWT access token for authentication	None
refresh_token	str | None	JWT refresh token for automatic token refresh	None
api_key	str | None	An API key (ysk_…) created on the account page. Sent as the bearer credential in place of a session token; it never expires mid-run and is never refreshed. Exclusive with token and refresh_token.	None
timeout	float	Request timeout in seconds	30.0
max_retries	int	Maximum number of retry attempts for failed requests	3
verify_connection	bool	Check connection health on first request (default: True)	True
strict_version_check	bool	Fail if SDK and API yousleep_common versions don't match (default: True). If False, only warns on mismatch.	True

close() async

Close the HTTP client and cleanup resources.

delete(path, **kwargs) async

Make a DELETE request.

from_api_key(base_url, api_key, **kwargs) classmethod

Create a client that authenticates with an API key.

The machine counterpart of from_credentials: no sign-in round trip, because a key is presented directly as the bearer credential. The key is never refreshed; a 401 means it is unknown, revoked or expired.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL of the API	required
api_key	str	An API key (ysk_…) created on the account page	required
**kwargs	Any	Additional arguments passed to AsyncClient constructor	{}

Returns:

Type	Description
AsyncClient	A client ready to use — enter it as an async context manager

Example

client = AsyncClient.from_api_key(
    base_url="https://api.yousleep.ai", api_key=os.environ["YOUSLEEP_API_KEY"]
)
async with client:
    projects = await client.projects.list()

from_credentials(base_url, credentials, **kwargs) async classmethod

Create a client by authenticating with credentials.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL of the API	required
credentials	UserAuthentication	User authentication credentials (email and password)	required
**kwargs	Any	Additional arguments passed to AsyncClient constructor	{}

Returns:

Type	Description
AsyncClient	Authenticated AsyncClient instance

Raises:

Type	Description
AuthenticationError	If authentication fails

Example

from yousleep_common.models import UserAuthentication

credentials = UserAuthentication(
    email="user@example.com",
    password="secure_password"
)
client = await AsyncClient.from_credentials(
    base_url="https://api.yousleep.ai",
    credentials=credentials
)

get(path, **kwargs) async

Make a GET request.

get_response(path, **kwargs) async

Make a GET request and return the raw response (headers + body).

Same auth/retry machinery as :meth:get; for callers that read response headers such as X-Total-Count.

get_text(path, **kwargs) async

Make a GET request and return the raw response body as text.

For non-JSON endpoints (e.g. the report audit CSV); goes through the same auth/retry machinery as :meth:get.

patch(path, **kwargs) async

Make a PATCH request.

post(path, **kwargs) async

Make a POST request.

put(path, **kwargs) async

Make a PUT request.