Skip to main content
The Organization Service provides endpoints for creating and managing organizations, which are the top-level containers for all resources in the system.

​
Authentication

All endpoints require a valid Bearer token in the Authorization header.

​
Base URL

/api/org

​
Endpoints

​
List Organizations

Retrieve a list of organizations the authenticated user belongs to. 
curl -X GET {{baseUrl}}/api/org/list \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/org/list

​
Create Organization

Create a new organization. 
curl -X POST {{baseUrl}}/api/org/create_org?name=New%20Organization \
  -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: POST /api/org/create_org Query Parameters:
ParameterRequiredDescription
nameYesName of the organization to create
Response:
FieldTypeDescription
idstring (UUID)Organization ID
namestringOrganization name
created_atstring (datetime)Creation timestamp
updated_atstring (datetime)Last update timestamp
user_roleobjectRole of the user in this organization
user_role.role_idstring (UUID)Role ID
user_role.role_namestringRole name
user_role.levelintegerRole level/hierarchy (higher means more permissions)

​
Add Member to Organization

Add an existing user as a member to an organization with a specific role. 
curl -X POST {{baseUrl}}/api/org/add_member \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "d07897e2-1ddf-4f11-9434-5fb6f2f5c20d",
    "user_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
    "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l"
  }'
Endpoint: POST /api/org/add_member Request Body:
FieldTypeRequiredDescription
organization_idstring (UUID)YesID of the organization
user_idstring (UUID)YesID of the user to add
role_idstring (UUID)YesID of the role to assign to the user
Response:
FieldTypeDescription
messagestringSuccess message
This endpoint requires the team_members feature to be enabled for the organization. It adds an existing user to the organization with the specified role and sets their status to “active”.
To add a new user via invitation, use the Invitations Service instead. This endpoint only works for users who already have accounts in the system.

​
Error Responses

Status CodeDescription
400Bad Request - Invalid input or validation error
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions
409Conflict - Organization with the same name already exists
500Internal Server Error - Server-side error

​
Implementation Notes

  • Every user automatically gets a personal organization upon signup
  • When an organization is created, default roles are automatically created:
    • Owner (Level 100): Full system access
    • Admin (Level 80): Administrative capabilities
    • Member (Level 20): Standard user access
    • Guest (Level 10): Limited access
  • The creating user is automatically assigned the Owner role
  • Organizations serve as isolated environments with their own resources, users, and permissions
  • All resources (knowledge bases, conversations, etc.) are created within the context of an organization