user

User endpoint handlers.

`UserEndpoint` ¶

Bases: BaseEndpoint

Handles user-related API endpoints.

Provides access to user information, history, and usage statistics.

`change_password(request)` `async` ¶

Change the authenticated user's password.

Parameters:

Name	Type	Description	Default
`request`	`ChangePasswordRequest`	Current password (for verification) and the new password	required

Returns:

Type	Description
`MessageResponse`	Message confirming the password change

Raises:

Type	Description
`AuthenticationError`	If not authenticated
`ValidationError`	If the current password is wrong or the new one does not meet complexity requirements

Example

from yousleep_common.models import ChangePasswordRequest

await client.user.change_password(
    ChangePasswordRequest(
        current_password="old-password",
        new_password="new-password",
    )
)

`create_api_key(request)` `async` ¶

Create an API key; the response carries the secret exactly once.

The account must have been enabled for keys by an administrator, and the request carries the account password again.

Parameters:

Name	Type	Description	Default
`request`	`ApiKeyCreate`	Name, scopes, optional description and lifetime, password	required

Returns:

Type	Description
`ApiKeyCreated`	The key with its secret — store it now, it is not shown again

Raises:

Type	Description
`ForbiddenError`	If the account may not create keys, or the client is itself authenticated with a key
`ValidationError`	If a scope is refused or the lifetime exceeds the server's maximum

Example

from yousleep_common.models import ApiKeyCreate
from yousleep_common.types import Permission

created = await client.user.create_api_key(
    ApiKeyCreate(
        name="Nightly pipeline",
        scopes=[Permission.RECORDING_CREATE, Permission.ANALYSIS_CREATE],
        expires_in_days=90,
        password="…",
    )
)
secret_manager.store("YOUSLEEP_API_KEY", created.secret)

`delete()` `async` ¶

Delete the current user account.

This is a permanent action that deletes all user data.

Returns:

Type	Description
`MessageResponse`	Message confirming deletion

Raises:

Type	Description
`AuthenticationError`	If not authenticated

Example

response = await client.user.delete()
print(response.message)

`export_audit(filters=None)` `async` ¶

Return your own audit trail as CSV text, oldest first.

`get_current()` `async` ¶

Get information about the currently authenticated user.

Returns:

Type	Description
`UserOut`	User information

Raises:

Type	Description
`AuthenticationError`	If not authenticated

Example

user = await client.user.get_current()
print(f"Email: {user.email}")
print(f"Organization: {user.organization}")

`get_organization()` `async` ¶

Get the caller's organization and their role in it.

Every project, credit balance and storage figure belongs to it.

Returns:

Type	Description
`UserOrganizationOut`	The organization overview.

`history(*, since_num_days=None, analysis_config_id=None, project_name=None, study_name=None, status=None, analysis_type=None, order=None, offset=None, limit=None)` `async` ¶

Get one page of the user's analysis history.

The history covers every analysis in every project the user can open, deleted ones included, ordered by the time each was queued. The server returns the newest first and a bounded page by default; total on the response counts every match, so page with offset until it is reached.

Parameters:

Name	Type	Description	Default
`since_num_days`	`int \| None`	Only analyses from the last `since_num_days` days	`None`
`analysis_config_id`	`str \| None`	Only analyses of this configuration	`None`
`project_name`	`str \| None`	Only analyses in the project with this name	`None`
`study_name`	`str \| None`	Only analyses in studies with this name	`None`
`status`	`AnalysisStatus \| None`	Only analyses in this status	`None`
`analysis_type`	`AnalysisType \| None`	Only analyses of this type	`None`
`order`	`Literal['asc', 'desc'] \| None`	`"desc"` (the default, newest first) or `"asc"`	`None`
`offset`	`int \| None`	Analyses to skip	`None`
`limit`	`int \| None`	Maximum analyses to return; the server's default when omitted	`None`

Returns:

Type	Description
`HistoryResponse`	Analysis history with list of analyses and total count

Raises:

Type	Description
`AuthenticationError`	If not authenticated

Example

history = await client.user.history(since_num_days=7, limit=100)
print(f"Total analyses: {history.total}")
for analysis in history.history:
    print(f"- {analysis.id}: {analysis.status}")

`list_api_keys()` `async` ¶

List the account's API keys — everything except the secret.

Expired keys stay listed until deleted, so the owner can see what needs rotating.

Returns:

Type	Description
`list[ApiKeyOut]`	The keys, newest first

Example

for key in await client.user.list_api_keys():
    print(key.name, key.prefix, key.expires_at, key.expired)

`list_audit(filters=None, *, offset=0, limit=50)` `async` ¶

Return your own audit trail, newest first.

Events about your account and membership, and what you did in projects. filters narrows by event types, a time window or an item.

Returns:

Type	Description
`AuditEventListResponse`	One page of events (`limit` at most 200) and the total.

`revoke_api_key(key_id)` `async` ¶

Revoke an API key; it stops authenticating on its next request.

Parameters:

Name	Type	Description	Default
`key_id`	`UUID \| str`	The key's id, from the listing	required

Returns:

Type	Description
`MessageResponse`	A confirmation message

Raises:

Type	Description
`NotFoundError`	If the account holds no such key

`update_profile(request)` `async` ¶

Update the authenticated user's own profile (name/position).

Omitted fields are left unchanged. Email/password changes go through their dedicated flows; usage_type changes are admin-mediated.

Parameters:

Name	Type	Description	Default
`request`	`UserProfileUpdate`	The profile fields to change	required

Returns:

Type	Description
`UserOut`	The updated user

Example

from yousleep_common.models import UserProfileUpdate

user = await client.user.update_profile(
    UserProfileUpdate(name="Ada Lovelace", position="PI")
)

`usage(analysis_config_id, since_num_days=30)` `async` ¶

Get the user's analysis usage statistics for a specific analysis config.

Parameters:

Name	Type	Description	Default
`analysis_config_id`	`str`	ID of the analysis configuration to get usage for	required
`since_num_days`	`int`	Number of days to look back (default: 30)	`30`

Returns:

Type	Description
`AnalysisUsage`	Usage statistics including analysis count, credit cost, and signal hours

Raises:

Type	Description
`AuthenticationError`	If not authenticated

Example

usage = await client.user.usage("example-sleep-staging-analysis-v1")
print(f"Total analyses: {usage.analyses}")
print(f"Credit cost: {usage.credit_cost}")
print(f"Signal hours: {usage.signal_hours}")

`usage_detailed()` `async` ¶

Get detailed resource usage statistics.

Returns:

Type	Description
`ResourceUsage`	Resource usage with project, study, recording, and storage counts

Raises:

Type	Description
`AuthenticationError`	If not authenticated

Example

usage = await client.user.usage_detailed()
print(f"Projects: {usage.projects}")

`usage_limits()` `async` ¶

Get usage limits for the current user.

Returns:

Type	Description
`ResourceUsage`	Resource usage limits

Raises:

Type	Description
`AuthenticationError`	If not authenticated

Example

limits = await client.user.usage_limits()
print(f"Project limit: {limits.projects}")

user

UserEndpoint ¶

change_password(request) async ¶

create_api_key(request) async ¶

delete() async ¶

export_audit(filters=None) async ¶

get_current() async ¶

get_organization() async ¶

history(*, since_num_days=None, analysis_config_id=None, project_name=None, study_name=None, status=None, analysis_type=None, order=None, offset=None, limit=None) async ¶

list_api_keys() async ¶

list_audit(filters=None, *, offset=0, limit=50) async ¶

revoke_api_key(key_id) async ¶

update_profile(request) async ¶

usage(analysis_config_id, since_num_days=30) async ¶

usage_detailed() async ¶

usage_limits() async ¶

`UserEndpoint` ¶

`change_password(request)` `async` ¶

`create_api_key(request)` `async` ¶

`delete()` `async` ¶

`export_audit(filters=None)` `async` ¶

`get_current()` `async` ¶

`get_organization()` `async` ¶

`history(*, since_num_days=None, analysis_config_id=None, project_name=None, study_name=None, status=None, analysis_type=None, order=None, offset=None, limit=None)` `async` ¶

`list_api_keys()` `async` ¶

`list_audit(filters=None, *, offset=0, limit=50)` `async` ¶

`revoke_api_key(key_id)` `async` ¶

`update_profile(request)` `async` ¶

`usage(analysis_config_id, since_num_days=30)` `async` ¶

`usage_detailed()` `async` ¶

`usage_limits()` `async` ¶