Organization Service API

API reference for managing organizations

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.

Request

curl -X GET {{baseUrl}}/api/org/list \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/org/list

Create Organization

Create a new organization.

Request

curl -X POST {{baseUrl}}/api/org/create_org?name=New%20Organization \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: POST /api/org/create_org

Query Parameters:

Parameter	Required	Description
name	Yes	Name of the organization to create

Response:

Field	Type	Description
id	string (UUID)	Organization ID
name	string	Organization name
created_at	string (datetime)	Creation timestamp
updated_at	string (datetime)	Last update timestamp
user_role	object	Role of the user in this organization
user_role.role_id	string (UUID)	Role ID
user_role.role_name	string	Role name
user_role.level	integer	Role level/hierarchy (higher means more permissions)

Error Responses

Status Code	Description
400	Bad Request - Invalid input or validation error
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
409	Conflict - Organization with the same name already exists
500	Internal 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