Organizations API

The Organizations API provides programmatic access to create, manage, and query organizations and their members. All organization endpoints enforce RBAC -- the authenticated user must have a sufficient role in the target organization.

List organizations

GET /api/organization -- List all organizations the authenticated user belongs to.

Response

{
  "organizations": [
    {
      "id": "org_abc123",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "plan": "team",
      "role": "owner",
      "memberCount": 5,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ]
}

The role field indicates the authenticated user's role in each organization.

Create an organization

POST /api/organization -- Create a new organization. The authenticated user becomes the owner.

Request body

{
  "name": "Acme Corp",
  "slug": "acme-corp"
}

Response

{
  "id": "org_abc123",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "plan": "free",
  "createdAt": "2026-03-22T10:00:00Z"
}

New organizations start on the Free plan. Upgrade from the console or via the billing API.

Get organization details

GET /api/organization?orgId={orgId} -- Get details for a specific organization.

Requires: org.read permission (any role).

Response

{
  "id": "org_abc123",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "plan": "team",
  "memberCount": 5,
  "createdAt": "2026-01-15T10:00:00Z",
  "settings": {
    "defaultModel": "claude-sonnet-4-20250514",
    "sharedMemory": true,
    "webhookUrl": null
  }
}

Update organization

PATCH /api/organization -- Update organization settings.

Requires: org.update permission (admin or owner).

Request body

{
  "orgId": "org_abc123",
  "name": "Acme Corp (Updated)",
  "settings": {
    "defaultModel": "gpt-4o",
    "sharedMemory": false
  }
}

Only included fields are updated. Omitted fields are left unchanged.

Delete organization

DELETE /api/organization -- Delete an organization and all its data.

Requires: org.delete permission (owner only).

Request body

{
  "orgId": "org_abc123"
}

List members

GET /api/organization/members?orgId={orgId} -- List all members of an organization.

Requires: member.list permission (any role).

Response

{
  "members": [
    {
      "userId": "user_abc",
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "role": "owner",
      "joinedAt": "2026-01-15T10:00:00Z"
    },
    {
      "userId": "user_def",
      "name": "John Smith",
      "email": "john@acme.com",
      "role": "member",
      "joinedAt": "2026-02-01T14:30:00Z"
    }
  ]
}

Invite a member

POST /api/organization/members -- Invite a new member to an organization.

Requires: member.invite permission (admin or owner).

Request body

{
  "orgId": "org_abc123",
  "email": "new-member@example.com",
  "role": "member"
}

Response

{
  "invitation": {
    "id": "inv_abc123",
    "email": "new-member@example.com",
    "role": "member",
    "status": "pending",
    "expiresAt": "2026-04-05T10:00:00Z"
  }
}

The invitee receives an email with a link to accept. If they do not have a BroomVA account, they will be prompted to create one.

Update member role

PATCH /api/organization/members -- Change a member's role.

Requires: member.update_role permission (admin or owner). Removing admin status requires member.remove_admin (owner only).

Request body

{
  "orgId": "org_abc123",
  "userId": "user_def",
  "role": "admin"
}

Remove a member

DELETE /api/organization/members -- Remove a member from an organization.

Requires: member.remove permission (admin or owner).

Request body

{
  "orgId": "org_abc123",
  "userId": "user_def"
}

The removed member immediately loses access to all organization resources. Their personal workspace is unaffected.

Error responses