Organizations

Overview

Organizations let a team share agents, knowledge bases, and API secrets under one account, with role-based access and per-member usage tracking.

Base URL https://api.bithuman.ai. Authenticate with your api-secret; the acting account is resolved from the API secret. Organizations require a Pro, Business, or Enterprise plan — creating one or inviting members on a lower plan returns 403.

Roles. Every member is an owner, admin, or member. The table notes the minimum role each call needs; insufficient role returns 403. Seat caps by plan: Enterprise 50, Business 25, Pro 10.

Organizations

Create

POST /v2/organizations — create an org (Pro+). Adds you as owner. You can own one organization.

curl -X POST https://api.bithuman.ai/v2/organizations \
  -H "api-secret: $BITHUMAN_API_SECRET" -H "content-type: application/json" \
  -d '{"name":"Acme Inc"}'

import os, requests

resp = requests.post(
    "https://api.bithuman.ai/v2/organizations",
    headers={"api-secret": os.environ["BITHUMAN_API_SECRET"]},
    json={"name": "Acme Inc"},
)
print(resp.json())

const resp = await fetch("https://api.bithuman.ai/v2/organizations", {
  method: "POST",
  headers: {
    "api-secret": process.env.BITHUMAN_API_SECRET,
    "content-type": "application/json",
  },
  body: JSON.stringify({ name: "Acme Inc" }),
});
console.log(await resp.json());

{ "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "name": "Acme Inc", "slug": "acme-inc", "owner_user_id": "3f9a2c1b-8e7d-4a6f-9b21-c4d5e6f70812",
  "plan": "membership_business", "max_members": 25, "created_at": "2026-07-15T10:00:00Z" }

Errors: 403 plan gate · 409 you already own an org, or the slug is taken · 422 bad slug.

Get · Update · Delete

Members

List

GET /v2/organizations/{org_id}/members — any member. Owners/admins see pending & removed members too; regular members see only active ones.

{
  "org_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "members": [
    { "id": "8a0e1f2a-3b4c-4d5e-9f6a-7b8c9d0e1f2a", "user_id": "3f9a2c1b-8e7d-4a6f-9b21-c4d5e6f70812", "email": "owner@acme.com", "role": "owner", "status": "active" },
    { "id": "9b1f2a3b-4c5d-4e6f-8a7b-8c9d0e1f2a3b", "email": "invitee@acme.com", "role": "admin", "status": "pending" }
  ],
  "total": 2
}

Invite

POST /v2/organizations/{org_id}/members/invite — owner or admin.

{ "message": "Invitation sent", "invite_token": "…", "member_id": "8a0e5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d", "email_sent": true, "invite_url": "https://www.bithuman.ai/invite?token=…" }

The invite is valid 7 days. We email invite_url to the invitee; if email_sent is false, send them the link yourself. Errors: 403 seat limit reached or owner no longer Pro+ · 409 already a member or pending.

Other member operations

Organization API secrets

Org-scoped API secrets are what the Knowledge API and other org-shared resources use.

// POST → the secret is shown only on creation
{ "alias": "ci-pipeline", "secret": "k7m2…aC8e" }

Share an agent with the org

Usage & audit

// usage
{ "org_id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "usage": [ { "user_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "email": "dev@acme.com", "total_credits_used": 1240.5 } ] }

Audit events include create_org, invite_member, accept_invite, update_role, remove_member, create_api_key, delete_api_key, transfer_ownership, and delete_org.