organizations
Organization endpoint handlers.
The caller's organizations, their members, invitations and ownership.
OrganizationsEndpoint
¶
Bases: BaseEndpoint
Handles organization-related API endpoints.
Every account belongs to exactly one organization: the one created for it
at sign-up, or the one it joined by invitation. These methods manage that
organization and who belongs to it; client.user.get_organization
returns it.
accept_invitation(request)
async
¶
Accept an invitation as the signed-in account and join the organization.
The account's verified email must match the invited address. The account's own organization of one is retired; what joining means is in the Terms and Conditions, which every account has accepted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
InvitationToken
|
The token from the invitation link. |
required |
Returns:
| Type | Description |
|---|---|
UserOrganizationOut
|
The organization joined. |
accept_site_agreement(org_id, version)
async
¶
Accept the site agreement on the organization's behalf.
The owner only, and only the latest published version
(client.legal.site_agreement()). The acceptance is recorded and
never changed; a later version is accepted anew.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
version
|
int
|
The version read and accepted. |
required |
Returns:
| Type | Description |
|---|---|
SiteAgreementAcceptance
|
The acceptance as recorded. |
approve_runner(org_id, runner_id, fingerprint)
async
¶
Approve a pending runner of the organization's site pool.
Compare the fingerprint with the one the runner's host prints; the platform refuses an approval whose fingerprint differs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
runner_id
|
UUID | str
|
The runner to approve. |
required |
fingerprint
|
str
|
The whole fingerprint, |
required |
create_enrolment_token(org_id)
async
¶
Create a single-use token a runner enrols into the organization's site pool with.
The first token creates the pool. Owners and admins, while the organization holds site compute. The token is in this answer only.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
Returns:
| Type | Description |
|---|---|
EnrolmentTokenOut
|
The token, its pool, and when it expires. |
create_invitation(org_id, request)
async
¶
Invite an email address into the organization (owner or admin).
The invitee's own organization must be empty when they accept: it is retired, and they join this one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
request
|
InvitationCreate
|
The address and the role to join with. |
required |
Returns:
| Type | Description |
|---|---|
InvitationOut
|
The pending invitation. The token is only ever sent by email. |
estimate_credits(org_id, request)
async
¶
Price a plan of analyses as its runs would be priced.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
request
|
CreditEstimateRequest
|
The plan (studies, average recording length, analyses with their runs per study) and the margin to add. |
required |
Returns:
| Type | Description |
|---|---|
CreditEstimate
|
The cost per analysis, the total, and the total with the margin. |
export_audit(org_id, filters=None)
async
¶
Return the same events as CSV text, oldest first.
get(org_id)
async
¶
Get one of the caller's organizations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
Returns:
| Type | Description |
|---|---|
UserOrganizationOut
|
The organization as the caller sees it. |
Raises:
| Type | Description |
|---|---|
NotFoundError
|
If the caller is not a member of it. |
get_capabilities(org_id)
async
¶
Return the organization's capabilities on its own hardware.
Running analyses on its own hardware and keeping recordings at its site are each off until a platform administrator turns them on. The answer also says which version of the site agreement is published and which the organization accepted. Any member.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
get_compute_pool(org_id)
async
¶
Return the organization's site pool, or None before it has one.
An organization has at most one site pool, created with its first enrolment token. Owners and admins.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
get_usage(org_id)
async
¶
Return the organization's usage against its ceilings, member by member.
Owner and admins only. Storage and projects against their ceilings, then one row per member: the bytes and projects they hold (private ones included, without naming them), their analyses and the credits those cost.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
Returns:
| Type | Description |
|---|---|
OrganizationUsageOut
|
The organization's totals and one row per member, largest first. |
list_audit(org_id, filters=None, *, offset=0, limit=50)
async
¶
Return the organisation's audit trail (its owner and admins).
Its members, invitations and roles, its storage and credits, and every
event about a project the organisation could see when it happened.
Newest first; filters narrows by event types, a time window, a
person or an item.
Returns:
| Type | Description |
|---|---|
AuditEventListResponse
|
One page of events ( |
list_capability_requests(org_id, limit=50, offset=0)
async
¶
Return the organization's requests for capabilities, newest first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
limit
|
int
|
Maximum requests to return. |
50
|
offset
|
int
|
Requests to skip from the newest. |
0
|
list_credit_requests(org_id, limit=50, offset=0)
async
¶
Return the organization's grant and extension requests, newest first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
limit
|
int
|
Maximum requests to return. |
50
|
offset
|
int
|
Requests to skip from the newest. |
0
|
list_grants(org_id)
async
¶
Return the organization's research grants, soonest to expire first.
Each with what remains of it; the starter grant, which never expires, comes last.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
list_invitations(org_id)
async
¶
List an organization's open invitations: pending, and recently expired.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
Returns:
| Type | Description |
|---|---|
list[InvitationOut]
|
The invitations, newest first. |
list_members(org_id)
async
¶
List an organization's members.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
Returns:
| Type | Description |
|---|---|
list[MemberOut]
|
The members with their roles, owner first. |
list_runners(org_id, *, offset=0, limit=50)
async
¶
List the runners of the organization's site pool, newest first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
offset
|
int
|
Pagination offset (default: 0). |
0
|
limit
|
int
|
Maximum runners to return (default: 50, max: 200). |
50
|
lookup_invitation(request)
async
¶
Describe the invitation behind a link, before accepting it.
No authentication is required: the token itself is the credential.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
InvitationToken
|
The token from the invitation link. |
required |
Returns:
| Type | Description |
|---|---|
InvitationPreview
|
The organization, inviter and invited address. |
Raises:
| Type | Description |
|---|---|
NotFoundError
|
If the token is unknown, expired or revoked. |
release_runner(org_id, runner_id)
async
¶
Release a quarantined runner of the organization's site pool.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
runner_id
|
UUID | str
|
The runner to release. |
required |
remove_member(membership_id)
async
¶
Remove a member from the organization, or leave it by removing yourself.
Projects the member owned pass to the organization's owner, and the member receives a fresh organization of their own. The owner cannot be removed; ownership is transferred first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
membership_id
|
UUID | str
|
The membership to end. The caller's own membership id
is on |
required |
Returns:
| Type | Description |
|---|---|
MessageResponse
|
A message confirming the removal. |
request_capability(org_id, request)
async
¶
Ask the platform's administrators to turn a capability on.
The owner only, one request per capability at a time, and none for a capability that is already on.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
request
|
CapabilityRequestCreate
|
The capability, and what it is for. |
required |
Returns:
| Type | Description |
|---|---|
CapabilityRequestOut
|
The pending request. |
request_extension(org_id, grant_id, request)
async
¶
Ask for more time on a grant before it expires.
Owner and admins only.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
grant_id
|
UUID | str
|
The grant to extend. |
required |
request
|
ExtensionRequestCreate
|
The extra time asked for, and why. |
required |
Returns:
| Type | Description |
|---|---|
CreditRequestOut
|
The pending request. |
request_grant(org_id, request)
async
¶
Ask for a research grant for a planned piece of work.
Owner and admins only. An administrator reviews the plan, the computed cost and the amount asked for, and approves or declines it; the requester is emailed the decision.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
request
|
GrantRequestCreate
|
The plan, the margin, the amount asked for, the term and what the research is. |
required |
Returns:
| Type | Description |
|---|---|
CreditRequestOut
|
The pending request. |
revoke_invitation(invitation_id)
async
¶
Withdraw a pending invitation (owner or admin).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
invitation_id
|
UUID | str
|
The invitation id. |
required |
Returns:
| Type | Description |
|---|---|
MessageResponse
|
A message confirming the revocation. |
revoke_runner(org_id, runner_id)
async
¶
Revoke a runner of the organization's site pool; it is refused from its next request on.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
runner_id
|
UUID | str
|
The runner to revoke. |
required |
transfer_ownership(org_id, request)
async
¶
Hand the organization to another member (owner only).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
request
|
OwnershipTransfer
|
The new owner and the caller's password. |
required |
Returns:
| Type | Description |
|---|---|
UserOrganizationOut
|
The organization, with the caller's new role (admin). |
update(org_id, request)
async
¶
Rename an organization (owner or admin).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
org_id
|
UUID | str
|
The organization id. |
required |
request
|
OrganizationUpdate
|
The new name. |
required |
Returns:
| Type | Description |
|---|---|
UserOrganizationOut
|
The updated organization. |
update_member_role(membership_id, request)
async
¶
Change a member's role between admin and member.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
membership_id
|
UUID | str
|
The membership to change (from |
required |
request
|
MemberRoleUpdate
|
The new role. |
required |
Returns:
| Type | Description |
|---|---|
MemberOut
|
The updated member. |