Organizations
Personal workspaces and organizations: who is in them, what each role may do, invitations, and the plan, quotas and overview of the one you are working in.
Every record belongs to an organization. An account starts with one of its own, a personal workspace that only that account can use. It can also create team organizations, invite people into them, and be invited into other people's. Each organization has its own projects, models, API keys, plan and quotas. An organization can have more than one member once it is on the Team plan: see Billing.
A request acts in one organization. An API key acts in the organization it was created in. A session token acts in the one it names: signing in gives a token for the personal workspace, and switching gives one for another organization the account belongs to. /v1/organization is the organization the request acts in. /v1/organizations and /v1/invitations are about the signed-in account, whichever organization its token names.
| Role | May |
|---|---|
owner | Everything an admin may, plus making and unmaking owners and deleting the organization. An organization always has at least one. |
admin | Invite and remove people, change roles (not an owner's), change settings, transfer models and projects out, revoke any API key. |
member | Create and change projects and models, log predictions, run explanations and analyses, create API keys and revoke their own. |
viewer | Read everything, and fork models and projects to an organization where they can write. Any other write is 403 read_only_role. |
The owner of a personal workspace is its only member. A session whose organization the account has left, or that has been deleted, gets 403 organization_access_revoked on every route that acts in an organization, and can still list its organizations and switch.
#The Organization object
The same object describes a personal workspace and a team. role and member_count are set when the caller is a signed-in user.
Attributes
org_ identifier.Display name, and a slug unique across Kaimei. personal is reserved.
personal for an account's own workspace, team for an organization people are invited to.free, standard, team or enterprise. A new organization starts on free.Free-form settings, including self-imposed quotas.
{plan, limits, usage}. Set on GET /v1/organization.The role the caller works with here: owner, admin, member or viewer. An admin or member of an organization that has left the Team plan is a viewer until it is back on it; see Billing for what its owners can do meanwhile. null for an API key.
How many people are in it.
What the plan allows here. members is true when people can be invited: an organization on team or enterprise.
{
"object": "organization",
"id": "org_5b1f0c9a7d2e4f6a8c3b",
"name": "Acme Risk",
"slug": "acme-risk",
"plan": "team",
"kind": "team",
"settings": {},
"quotas": null,
"role": "owner",
"member_count": 3,
"features": {"members": true},
"created_at": "2026-11-18T09:12:44.118203Z"
}#List your organizations
/v1/organizationsSession token onlyEvery organization the signed-in account belongs to, each with the account's role in it: the personal workspace first, then teams by name.
Query parameters
Items per page.
Items to skip.
Returns
client.auth.login(email="you@example.com", password="...")
for org in client.organizations.list().data:
print(org.kind, org.slug, org.role)curl https://api.kaimei.ai/v1/organizations \
-H "Authorization: Bearer $SESSION_TOKEN"{
"object": "list",
"data": [
{
"object": "organization",
"id": "org_c72a301b93331f42b7b9",
"name": "Kaimei Demo",
"slug": "kaimei-demo",
"plan": "free",
"kind": "personal",
"settings": {},
"quotas": null,
"role": "owner",
"member_count": 1,
"features": {"members": false},
"created_at": "2026-10-31T22:37:25.334655Z"
},
{
"object": "organization",
"id": "org_5b1f0c9a7d2e4f6a8c3b",
"name": "Acme Risk",
"slug": "acme-risk",
"plan": "team",
"kind": "team",
"settings": {},
"quotas": null,
"role": "owner",
"member_count": 3,
"features": {"members": true},
"created_at": "2026-11-18T09:12:44.118203Z"
}
],
"total": 2,
"limit": 50,
"offset": 0,
"has_more": false
}#Create an organization
/v1/organizationsSession token onlyA new, empty team organization on the free plan, owned by whoever creates it. The session keeps acting where it was: switch to work in the new one. An account may own 10. 403 organization_limit beyond that. It can be used by its owner straight away, and needs the Team plan before anyone else can be invited.
Body parameters
1 to 120 characters.
Unique across Kaimei (409 slug_taken). Derived from the name when omitted.
Returns
role owner. 201.org = client.organizations.create(name="Acme Risk")
client.auth.switch(org.slug)curl -X POST https://api.kaimei.ai/v1/organizations \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Acme Risk"}'{
"object": "organization",
"id": "org_5b1f0c9a7d2e4f6a8c3b",
"name": "Acme Risk",
"slug": "acme-risk",
"plan": "free",
"kind": "team",
"settings": {},
"quotas": null,
"role": "owner",
"member_count": 1,
"features": {"members": false},
"created_at": "2026-11-18T09:12:44.118203Z"
}#Retrieve the organization
/v1/organizationAPI key or sessionThe organization the token acts for, with its plan limits and this month's usage under quotas.
Returns
id, name, slug, kind, plan, settings, quotas {plan, limits, usage}, role, member_count, created_at.org = client.organization.retrieve()
print(org.plan, org.quotas["usage"]["explanations_per_month"], "/", org.quotas["limits"]["explanations_per_month"])curl https://api.kaimei.ai/v1/organization \
-H "Authorization: Bearer $KAIMEI_API_KEY"{
"object": "organization",
"id": "org_c72a301b93331f42b7b9",
"name": "Kaimei Demo",
"slug": "kaimei-demo",
"plan": "free",
"kind": "personal",
"settings": {},
"quotas": {
"plan": "free",
"limits": {
"models": 10,
"api_keys": 5,
"predictions_per_month": 5000,
"explanations_per_month": 500,
"analyses_per_month": 20
},
"usage": {
"models": 4,
"api_keys": 2,
"predictions_per_month": 1560,
"explanations_per_month": 27,
"analyses_per_month": 6
}
},
"role": "owner",
"member_count": 1,
"features": {"members": false},
"created_at": "2026-10-31T22:37:25.334655Z"
}#Update the organization
/v1/organizationAdmin session onlyRename the organization or change its settings. Owners and admins only, from a dashboard session. settings.quotas may lower any plan limit (models, api_keys, predictions_per_month, explanations_per_month, analyses_per_month) but never raise one; 403 quota_override_not_allowed otherwise.
Body parameters
Merged into the existing settings. quotas is validated as described.
Returns
client.auth.login(email="owner@example.com", password="...")
client.organization.update(settings={"quotas": {"explanations_per_month": 300}})curl -X PATCH https://api.kaimei.ai/v1/organization \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"settings": {"quotas": {"explanations_per_month": 300}}}'{
"object": "organization",
"id": "org_c72a301b93331f42b7b9",
"name": "Kaimei Demo",
"slug": "kaimei-demo",
"plan": "free",
"kind": "personal",
"settings": {
"quotas": {"explanations_per_month": 300}
},
"quotas": null,
"role": "owner",
"member_count": 1,
"features": {"members": false},
"created_at": "2026-10-31T22:37:25.334655Z"
}#Delete the organization
/v1/organizationOwner session onlyDelete a team and every project, model, prediction, explanation, analysis, insight and API key in it, for all of its members. Owners only, and it cannot be undone: transfer what should be kept first. A subscription the organization pays for is cancelled at once, and if Stripe cannot be reached to cancel it nothing is deleted (502 billing_provider_error). A personal workspace is not deleted this way (403 personal_workspace).
Query parameters
The organization's slug. 400 confirmation_required when it does not match.
Returns
client.organization.delete(confirm="acme-risk")curl -X DELETE https://api.kaimei.ai/v1/organization?confirm=acme-risk \
-H "Authorization: Bearer $SESSION_TOKEN"{
"id": "org_5b1f0c9a7d2e4f6a8c3b",
"object": "organization",
"deleted": true
}#Workspace overview
/v1/organization/overviewAPI key or sessionThe dashboard home page in one call: counts across the workspace, a daily series for the last 31 days, the 12 most recently updated models, the 8 most recent explanations and the 6 most recent medium or high insights as alerts.
Returns
{organization, counts, series, models, recent_explanations, alerts}.overview = client.organization.overview()
print(overview.counts)
for alert in overview.alerts:
print(alert["severity"], alert["type"], alert["summary"])curl https://api.kaimei.ai/v1/organization/overview \
-H "Authorization: Bearer $KAIMEI_API_KEY"{
"organization": {
"object": "organization",
"id": "org_c72a301b93331f42b7b9",
"name": "Kaimei Demo",
"slug": "kaimei-demo",
"plan": "free",
"kind": "personal",
"settings": {},
"quotas": null,
"role": "owner",
"member_count": 1,
"features": {"members": false},
"created_at": "2026-10-31T22:37:25.334655Z"
},
"counts": {
"models": 5,
"active_models": 5,
"predictions_30d": 860,
"explanations_30d": 60,
"predictions_total": 860,
"explanations_total": 60,
"analyses_total": 5,
"analyses_running": 0,
"insights_total": 31
},
"series": [
{"date": "2026-10-01", "predictions": 0, "explanations": 0},
…,
{
"date": "2026-10-31",
"predictions": 212,
"explanations": 24
}
],
"models": [
{
"object": "model",
"id": "mdl_8f795e8afd954a787785",
"slug": "cats-dogs-v1",
…: …
},
…
],
"recent_explanations": [
{
"object": "explanation",
"id": "exp_7d7add16c796eafac087",
…: …
},
…
],
"alerts": [
{
"object": "insight",
"id": "ins_a0a2b5c4a5ddb552758a",
"type": "drift",
"severity": "medium",
…: …
},
…
]
}#List members
/v1/organization/membersAPI key or sessionThe people in the organization, in the order they joined. A photo the member uploaded is inlined in avatar_url when it is under 64 KB.
Query parameters
Items per page.
Items to skip.
Returns
id, user_id, email, name, avatar_url, role, is_you, joined_at, last_login_at.for member in client.organization.members().data:
print(member.email, member.role)curl https://api.kaimei.ai/v1/organization/members \
-H "Authorization: Bearer $KAIMEI_API_KEY"{
"object": "list",
"data": [
{
"object": "member",
"id": "mem_2c7d9e0f1a3b4c5d6e7f",
"user_id": "usr_99d45281ca85b8a7cc92",
"email": "demo@kaimei.ai",
"name": "Kaimei Demo",
"avatar_url": null,
"role": "owner",
"is_you": true,
"joined_at": "2026-11-18T09:20:03.551870Z",
"last_login_at": "2026-11-18T09:19:58.204611Z"
},
{
"object": "member",
"id": "mem_2c7d9e0f1a3b4c5d6e7f",
"user_id": "usr_41a0c2d87be35f6a9d10",
"email": "grace@example.com",
"name": "Grace",
"avatar_url": null,
"role": "member",
"is_you": false,
"joined_at": "2026-11-18T09:20:03.551870Z",
"last_login_at": "2026-11-18T09:19:58.204611Z"
}
],
"total": 2,
"limit": 50,
"offset": 0,
"has_more": false
}#Change a member's role
/v1/organization/members/{user_id}Admin session onlyOwners and admins. Only an owner may make someone an owner or change an owner's role (403 owner_required). The last owner cannot be demoted (409 last_owner). Moving an owner or admin down to member or viewer withdraws the invitations they sent that nobody has answered, since they can no longer invite. Not available on a personal workspace (403 personal_workspace).
Path parameters
The member's user_id.
Body parameters
owner, admin, member or viewer.Returns
client.organization.update_member("usr_41a0c2d87be35f6a9d10", role="admin")curl -X PATCH https://api.kaimei.ai/v1/organization/members/usr_41a0c2d87be35f6a9d10 \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"role": "admin"}'{
"object": "member",
"id": "mem_2c7d9e0f1a3b4c5d6e7f",
"user_id": "usr_41a0c2d87be35f6a9d10",
"email": "grace@example.com",
"name": "Grace",
"avatar_url": null,
"role": "admin",
"is_you": false,
"joined_at": "2026-11-18T09:20:03.551870Z",
"last_login_at": "2026-11-18T09:19:58.204611Z"
}#Remove a member, or leave
/v1/organization/members/{user_id}Session token onlyAn owner or admin removes someone else; only an owner removes an owner. Any member removes themselves, which is leaving. The last owner cannot leave (409 last_owner). The member's sessions lose access on their next request, and every API key they created in the organization is revoked in the same step, so a key cannot outlive its creator's access. The keys stay in GET /v1/api-keys, revoked, with created_by_* filled in; api_keys_revoked says how many were still active. The invitations they sent that nobody has answered are withdrawn too, so none can bring them back in; invitations_revoked counts them. Rejoining later does not bring the keys back. Create replacements first if a service depends on them: GET /v1/api-keys?created_by=<user_id> lists them.
Path parameters
The member's user_id. Your own to leave.
Returns
api_keys_revoked and invitations_revoked.client.organization.remove_member("usr_41a0c2d87be35f6a9d10")curl -X DELETE https://api.kaimei.ai/v1/organization/members/usr_41a0c2d87be35f6a9d10 \
-H "Authorization: Bearer $SESSION_TOKEN"{
"id": "mem_2c7d9e0f1a3b4c5d6e7f",
"object": "member",
"deleted": true,
"api_keys_revoked": 2,
"invitations_revoked": 0
}#Invite someone
/v1/organization/invitationsAdmin session onlyOffer an email address a place in the organization. The response carries invite_url, which is shown only here: the server stores a hash of its token. The link is also emailed when the server has mail configured; email_sent says whether it went out. It works for 7 days, once, and only for an account with that email address. Inviting an address that already has a pending invitation replaces it, and the earlier link stops working. 409 already_member when the address is already in the organization. 403 plan_required when the organization is not on the Team plan or above. 30 invitations per hour, more on higher plans.
Body parameters
admin, member or viewer. Ownership is given to a member, not offered in an invitation.Returns
invite_url and email_sent. 201.invitation = client.organization.invite(email="grace@example.com", role="member")
print(invitation.invite_url, invitation.email_sent)curl -X POST https://api.kaimei.ai/v1/organization/invitations \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"email": "grace@example.com", "role": "member"}'{
"object": "invitation",
"id": "inv_8e3f1a2b4c5d6e7f9a0b",
"email": "grace@example.com",
"role": "member",
"status": "pending",
"organization_id": "org_5b1f0c9a7d2e4f6a8c3b",
"organization_name": "Acme Risk",
"organization_slug": "acme-risk",
"invited_by_name": "Kaimei Demo",
"invited_by_email": "demo@kaimei.ai",
"created_at": "2026-11-18T09:14:10.730112Z",
"expires_at": "2026-11-25T09:14:10.729004Z",
"invite_url": "https://dashboard.kaimei.ai/invite?token=Zr2mA1…",
"email_sent": true
}#List invitations sent
/v1/organization/invitationsAdmin session onlyInvitations sent from the organization, newest first. Pending ones by default.
Query parameters
pending, accepted, declined, revoked, expired or all.Items per page.
Items to skip.
Returns
id, email, role, status, organization_id, organization_name, organization_slug, invited_by_name, invited_by_email, created_at, expires_at.pending = client.organization.invitations().datacurl https://api.kaimei.ai/v1/organization/invitations \
-H "Authorization: Bearer $SESSION_TOKEN"{
"object": "list",
"data": [
{
"object": "invitation",
"id": "inv_8e3f1a2b4c5d6e7f9a0b",
"email": "grace@example.com",
"role": "member",
"status": "pending",
"organization_id": "org_5b1f0c9a7d2e4f6a8c3b",
"organization_name": "Acme Risk",
"organization_slug": "acme-risk",
"invited_by_name": "Kaimei Demo",
"invited_by_email": "demo@kaimei.ai",
"created_at": "2026-11-18T09:14:10.730112Z",
"expires_at": "2026-11-25T09:14:10.729004Z"
}
],
"total": 1,
"limit": 50,
"offset": 0,
"has_more": false
}#Send an invitation again
/v1/organization/invitations/{invitation_id}/resendAdmin session onlyA new link for a pending or expired invitation, valid for another 7 days. The old link stops working. 409 for one that was accepted, declined or revoked.
Path parameters
Returns
invite_url and email_sent.fresh = client.organization.resend_invitation("inv_8e3f1a2b4c5d6e7f9a0b")curl -X POST https://api.kaimei.ai/v1/organization/invitations/inv_8e3f1a2b4c5d6e7f9a0b/resend \
-H "Authorization: Bearer $SESSION_TOKEN"{
"object": "invitation",
"id": "inv_8e3f1a2b4c5d6e7f9a0b",
"email": "grace@example.com",
"role": "member",
"status": "pending",
"organization_id": "org_5b1f0c9a7d2e4f6a8c3b",
"organization_name": "Acme Risk",
"organization_slug": "acme-risk",
"invited_by_name": "Kaimei Demo",
"invited_by_email": "demo@kaimei.ai",
"created_at": "2026-11-18T09:14:10.730112Z",
"expires_at": "2026-11-26T10:02:31.118220Z",
"invite_url": "https://dashboard.kaimei.ai/invite?token=Qd81xK…",
"email_sent": true
}#Withdraw an invitation
/v1/organization/invitations/{invitation_id}Admin session onlyThe link stops working. Withdrawing one that was already answered changes nothing.
Path parameters
Returns
client.organization.revoke_invitation("inv_8e3f1a2b4c5d6e7f9a0b")curl -X DELETE https://api.kaimei.ai/v1/organization/invitations/inv_8e3f1a2b4c5d6e7f9a0b \
-H "Authorization: Bearer $SESSION_TOKEN"{
"id": "inv_8e3f1a2b4c5d6e7f9a0b",
"object": "invitation",
"deleted": true
}#Invitations waiting for you
/v1/invitationsSession token onlyPending invitations sent to the signed-in account's email address, from any organization.
Query parameters
Items per page.
Items to skip.
Returns
for invitation in client.invitations.list().data:
print(invitation.organization_name, invitation.role)curl https://api.kaimei.ai/v1/invitations \
-H "Authorization: Bearer $SESSION_TOKEN"{
"object": "list",
"data": [
{
"object": "invitation",
"id": "inv_8e3f1a2b4c5d6e7f9a0b",
"email": "grace@example.com",
"role": "member",
"status": "pending",
"organization_id": "org_5b1f0c9a7d2e4f6a8c3b",
"organization_name": "Acme Risk",
"organization_slug": "acme-risk",
"invited_by_name": "Kaimei Demo",
"invited_by_email": "demo@kaimei.ai",
"created_at": "2026-11-18T09:14:10.730112Z",
"expires_at": "2026-11-25T09:14:10.729004Z"
}
],
"total": 1,
"limit": 50,
"offset": 0,
"has_more": false
}#Look at an invitation link
/v1/invitations/previewNo authenticationWhat a link offers, before anyone signs in: which organization, which role, and for which email address. account_exists says whether that address already has an account, so a page can offer sign-in or sign-up. 404 invitation_not_found for a token that is unknown or was replaced.
Body parameters
The token from the link.
Returns
{email, role, status, organization_name, invited_by_name, expires_at, account_exists}.offer = client.invitations.preview("Zr2mA1…")curl https://api.kaimei.ai/v1/invitations/preview \
-H "Content-Type: application/json" \
-d '{"token": "Zr2mA1…"}'{
"object": "invitation_preview",
"email": "grace@example.com",
"role": "member",
"status": "pending",
"organization_name": "Acme Risk",
"invited_by_name": "Kaimei Demo",
"expires_at": "2026-11-25T09:14:10.729004Z",
"account_exists": false
}#Accept an invitation
/v1/invitations/acceptSession token onlyJoin the organization with the invitation's role. Name the invitation by the token from its link, or by invitation_id when it was sent to the signed-in account's email. The account's email must be the one invited (403 invitation_email_mismatch). 409 invitation_expired, invitation_revoked, invitation_declined or invitation_accepted when it is no longer pending. It is also 409 invitation_revoked when whoever sent it is no longer an owner or admin there. 403 plan_required when the organization has left the Team plan since the invitation was sent; the invitation stays good for when it is back. The session keeps acting where it was: switch to work in the organization.
Body parameters
From the invitation link.
From GET /v1/invitations. Pass one of the two.
Returns
role.org = client.invitations.accept(token="Zr2mA1…")
client.auth.switch(org.id)curl -X POST https://api.kaimei.ai/v1/invitations/accept \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"token": "Zr2mA1…"}'{
"object": "organization",
"id": "org_5b1f0c9a7d2e4f6a8c3b",
"name": "Acme Risk",
"slug": "acme-risk",
"plan": "team",
"kind": "team",
"settings": {},
"quotas": null,
"role": "member",
"member_count": 3,
"features": {"members": true},
"created_at": "2026-11-18T09:12:44.118203Z"
}#Decline an invitation
/v1/invitations/declineSession token onlyTurn an invitation down. The link stops working, and the organization can send a new one.
Body parameters
From the invitation link.
From GET /v1/invitations. Pass one of the two.
Returns
204 No Content.client.invitations.decline(invitation_id="inv_8e3f1a2b4c5d6e7f9a0b")curl -X POST https://api.kaimei.ai/v1/invitations/decline \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"invitation_id": "inv_8e3f1a2b4c5d6e7f9a0b"}'