> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zyeta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET {{baseUrl}}/api/org/list \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  url = "{{baseUrl}}/api/org/list"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  const url = "{{baseUrl}}/api/org/list";
  const headers = {
      Authorization: "Bearer YOUR_TOKEN"
  };

  axios.get(url, { headers })
      .then(response => console.log(response.data))
      .catch(error => console.error(error));
  ```

  ```json Response theme={null}
  [
    {
      "id": "d07897e2-1ddf-4f11-9434-5fb6f2f5c20d",
      "name": "Acme Inc",
      "created_at": "2023-07-15T10:30:00Z",
      "updated_at": "2023-07-15T10:30:00Z",
      "user_role": {
        "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
        "role_name": "Owner",
        "level": 100
      }
    },
    {
      "id": "e18908f3-2eef-5f22-0545-6fc7f3f6d31e",
      "name": "Personal Workspace",
      "created_at": "2023-07-10T14:45:00Z",
      "updated_at": "2023-07-10T14:45:00Z",
      "user_role": {
        "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
        "role_name": "Owner",
        "level": 100
      }
    }
  ]
  ```
</CodeGroup>

**Endpoint:** `GET /api/org/list`

### Create Organization

Create a new organization.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST {{baseUrl}}/api/org/create_org?name=New%20Organization \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  url = "{{baseUrl}}/api/org/create_org"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN"
  }
  params = {
      "name": "New Organization"
  }

  response = requests.post(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  const url = "{{baseUrl}}/api/org/create_org";
  const headers = {
      Authorization: "Bearer YOUR_TOKEN"
  };
  const params = {
      name: "New Organization"
  };

  axios.post(url, null, { headers, params })
      .then(response => console.log(response.data))
      .catch(error => console.error(error));
  ```

  ```json Response theme={null}
  {
    "id": "f29a19e4-3fff-6033-1656-7fd8f4f7e42f",
    "name": "New Organization",
    "created_at": "2023-07-25T09:00:00Z",
    "updated_at": "2023-07-25T09:00:00Z",
    "user_role": {
      "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
      "role_name": "Owner",
      "level": 100
    }
  }
  ```
</CodeGroup>

**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.

<CodeGroup>
  ```bash Request theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "{{baseUrl}}/api/org/add_member"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }
  data = {
      "organization_id": "d07897e2-1ddf-4f11-9434-5fb6f2f5c20d",
      "user_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
      "role_id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l"
  }

  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  const url = "{{baseUrl}}/api/org/add_member";
  const headers = {
      Authorization: "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  };
  const data = {
      organization_id: "d07897e2-1ddf-4f11-9434-5fb6f2f5c20d",
      user_id: "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
      role_id: "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l"
  };

  axios.post(url, data, { headers })
      .then(response => console.log(response.data))
      .catch(error => console.error(error));
  ```

  ```json Response theme={null}
  {
    "message": "Member added successfully"
  }
  ```
</CodeGroup>

**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 |

<Note>
  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".
</Note>

<Warning>
  To add a new user via invitation, use the [Invitations Service](invitations-service) instead. This endpoint only works for users who already have accounts in the system.
</Warning>

## 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