Organizations

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.

RoleMay
ownerEverything an admin may, plus making and unmaking owners and deleting the organization. An organization always has at least one.
adminInvite and remove people, change roles (not an owner's), change settings, transfer models and projects out, revoke any API key.
memberCreate and change projects and models, log predictions, run explanations and analyses, create API keys and revoke their own.
viewerRead 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

idstring
org_ identifier.
name / slugstring

Display name, and a slug unique across Kaimei. personal is reserved.

kindstring
personal for an account's own workspace, team for an organization people are invited to.
planstring
free, standard, team or enterprise. A new organization starts on free.
settingsobject

Free-form settings, including self-imposed quotas.

quotasobject | null
{plan, limits, usage}. Set on GET /v1/organization.
rolestring | null

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.

member_countinteger | null

How many people are in it.

featuresobject

What the plan allows here. members is true when people can be invited: an organization on team or enterprise.

created_attimestamp

Example
{
  "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

GET/v1/organizationsSession token only

Every 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

limitintegeroptionaldefault 50

Items per page.

offsetintegeroptionaldefault 0

Items to skip.

Returns

A page of Organizations.
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"
200 OKResponse
{
  "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

POST/v1/organizationsSession token only

A 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

namestringrequired

1 to 120 characters.

slugstringoptional

Unique across Kaimei (409 slug_taken). Derived from the name when omitted.

Returns

The Organization, with 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"}'
201 CreatedResponse
{
  "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

GET/v1/organizationAPI key or session

The organization the token acts for, with its plan limits and this month's usage under quotas.

Returns

An Organization: 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"
200 OKResponse
{
  "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

PATCH/v1/organizationAdmin session only

Rename 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

namestringoptional

settingsobjectoptional

Merged into the existing settings. quotas is validated as described.

Returns

The Organization.
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}}}'
200 OKResponse
{
  "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

DELETE/v1/organizationOwner session only

Delete 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

confirmstringrequired

The organization's slug. 400 confirmation_required when it does not match.

Returns

A deletion receipt.
client.organization.delete(confirm="acme-risk")
curl -X DELETE https://api.kaimei.ai/v1/organization?confirm=acme-risk \
  -H "Authorization: Bearer $SESSION_TOKEN"
200 OKResponse
{
  "id": "org_5b1f0c9a7d2e4f6a8c3b",
  "object": "organization",
  "deleted": true
}

#Workspace overview

GET/v1/organization/overviewAPI key or session

The 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"
200 OKResponse
{
  "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

GET/v1/organization/membersAPI key or session

The 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

limitintegeroptionaldefault 50

Items per page.

offsetintegeroptionaldefault 0

Items to skip.

Returns

A page of Members: 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"
200 OKResponse
{
  "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

PATCH/v1/organization/members/{user_id}Admin session only

Owners 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

user_idstringrequired

The member's user_id.

Body parameters

rolestringrequired
owner, admin, member or viewer.

Returns

The Member.
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"}'
200 OKResponse
{
  "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

DELETE/v1/organization/members/{user_id}Session token only

An 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

user_idstringrequired

The member's user_id. Your own to leave.

Returns

A deletion receipt with 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"
200 OKResponse
{
  "id": "mem_2c7d9e0f1a3b4c5d6e7f",
  "object": "member",
  "deleted": true,
  "api_keys_revoked": 2,
  "invitations_revoked": 0
}

#Invite someone

POST/v1/organization/invitationsAdmin session only

Offer 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

emailstringrequired

rolestringoptionaldefault "member"
admin, member or viewer. Ownership is given to a member, not offered in an invitation.

Returns

The Invitation, with 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"}'
201 CreatedResponse
{
  "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

GET/v1/organization/invitationsAdmin session only

Invitations sent from the organization, newest first. Pending ones by default.

Query parameters

statusstringoptionaldefault "pending"
pending, accepted, declined, revoked, expired or all.
limitintegeroptionaldefault 50

Items per page.

offsetintegeroptionaldefault 0

Items to skip.

Returns

A page of Invitations: id, email, role, status, organization_id, organization_name, organization_slug, invited_by_name, invited_by_email, created_at, expires_at.
pending = client.organization.invitations().data
curl https://api.kaimei.ai/v1/organization/invitations \
  -H "Authorization: Bearer $SESSION_TOKEN"
200 OKResponse
{
  "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

POST/v1/organization/invitations/{invitation_id}/resendAdmin session only

A 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

invitation_idstringrequired

Returns

The Invitation, with its new 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"
200 OKResponse
{
  "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

DELETE/v1/organization/invitations/{invitation_id}Admin session only

The link stops working. Withdrawing one that was already answered changes nothing.

Path parameters

invitation_idstringrequired

Returns

A deletion receipt.
client.organization.revoke_invitation("inv_8e3f1a2b4c5d6e7f9a0b")
curl -X DELETE https://api.kaimei.ai/v1/organization/invitations/inv_8e3f1a2b4c5d6e7f9a0b \
  -H "Authorization: Bearer $SESSION_TOKEN"
200 OKResponse
{
  "id": "inv_8e3f1a2b4c5d6e7f9a0b",
  "object": "invitation",
  "deleted": true
}

#Invitations waiting for you

GET/v1/invitationsSession token only

Pending invitations sent to the signed-in account's email address, from any organization.

Query parameters

limitintegeroptionaldefault 50

Items per page.

offsetintegeroptionaldefault 0

Items to skip.

Returns

A page of Invitations.
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"
200 OKResponse
{
  "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

POST/v1/invitations/previewNo authentication

What 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

tokenstringrequired

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…"}'
200 OKResponse
{
  "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

POST/v1/invitations/acceptSession token only

Join 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

tokenstringoptional

From the invitation link.

invitation_idstringoptional

From GET /v1/invitations. Pass one of the two.

Returns

The Organization joined, with the account's 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…"}'
200 OKResponse
{
  "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

POST/v1/invitations/declineSession token only

Turn an invitation down. The link stops working, and the organization can send a new one.

Body parameters

tokenstringoptional

From the invitation link.

invitation_idstringoptional

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"}'