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)

Add Member to Organization

Add an existing user as a member to an organization with a specific role.

Request

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:

Field	Type	Required	Description
organization_id	string (UUID)	Yes	ID of the organization
user_id	string (UUID)	Yes	ID of the user to add
role_id	string (UUID)	Yes	ID of the role to assign to the user

Response:

Field	Type	Description
message	string	Success 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 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