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)

​
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