---
title: Organizational Units API
path: reference/api/organizational-units
status: published
---

# Organizational Units API

Reference for the `Organizational Units` endpoint group — 7 endpoints.

Generated from the live OpenAPI spec. Re-run `_generate_api_reference.py` after backend changes.

## Authentication

All endpoints require a Bearer JWT in the `Authorization` header unless noted otherwise. See [Concepts → Tokens and scopes](/docs/scaikey/concepts/tokens-and-scopes) and [Reference → OAuth endpoints](/docs/scaikey/reference/oauth-endpoints) for how to obtain one.

## Endpoints

### **GET** `/api/v1/tenants/{tenant_id}/ous`

_List Ous_

List organizational units in the tenant.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `search` | query | no | `string` \| `null` |  |
| `parent_id` | query | no | `string` \| `null` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`PaginatedResponse_OUListItem_`](#schema-paginatedresponse-oulistitem) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **POST** `/api/v1/tenants/{tenant_id}/ous`

_Create Ou_

Create a new organizational unit.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`OUCreate`](#schema-oucreate)

**Responses:**

| Status | Body |
|---|---|
| `201` | `application/json` → [`ApiResponse_OUResponse_`](#schema-apiresponse-ouresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/ous/tree`

_Get Ou Tree_

Get organizational units as a tree structure.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_list_OUTreeNode__`](#schema-apiresponse-list-outreenode) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **DELETE** `/api/v1/tenants/{tenant_id}/ous/{ou_id}`

_Delete Ou_

Delete an organizational unit.

strategy:
- BLOCK: Fail if has users or child OUs
- MOVE_UP: Move users and child OUs to parent
- CASCADE: Delete child OUs (users moved to parent)

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `ou_id` | path | yes | `string` |  |
| `strategy` | query | no | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `204` | Successful Response |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/ous/{ou_id}`

_Get Ou_

Get an organizational unit by ID.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `ou_id` | path | yes | `string` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_OUResponse_`](#schema-apiresponse-ouresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **PATCH** `/api/v1/tenants/{tenant_id}/ous/{ou_id}`

_Update Ou_

Update an organizational unit.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `ou_id` | path | yes | `string` |  |

**Request body:**

Required.

- `application/json` → [`OUUpdate`](#schema-ouupdate)

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`ApiResponse_OUResponse_`](#schema-apiresponse-ouresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

### **GET** `/api/v1/tenants/{tenant_id}/ous/{ou_id}/users`

_List Ou Users_

List users in an organizational unit.

**Parameters:**

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `tenant_id` | path | yes | `string` |  |
| `ou_id` | path | yes | `string` |  |
| `page` | query | no | `integer` |  |
| `per_page` | query | no | `integer` |  |
| `include_nested` | query | no | `boolean` |  |

**Responses:**

| Status | Body |
|---|---|
| `200` | `application/json` → [`PaginatedResponse`](#schema-paginatedresponse) |
| `422` | `application/json` → [`HTTPValidationError`](#schema-httpvalidationerror) |

---

## Schemas

Definitions for every type referenced by the endpoints above. Schema-to-schema references on this page link within the page; cross-page references would require visiting the linked page.

### `ApiResponse_OUResponse_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | [`OUResponse`](#schema-ouresponse) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `ApiResponse_list_OUTreeNode__`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array of [`OUTreeNode`](#schema-outreenode) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `HTTPValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `detail` | array of [`ValidationError`](#schema-validationerror) | no |  |

### `MetaResponse`

Metadata included in API responses.

| Field | Type | Required | Description |
|---|---|---|---|
| `request_id` | `string` \| `null` | no |  |
| `timestamp` | `string` (`date-time`) | no |  |

### `OUChildInfo`

Child OU info.

| Field | Type | Required | Description |
|---|---|---|---|
| `ou_id` | `string` | yes |  |
| `name` | `string` | yes |  |
| `path` | `string` | yes |  |
| `user_count` | `integer` | no | Default: `0` |
| `children` | array of [`OUChildInfo`](#schema-ouchildinfo) | no |  |

### `OUCreate`

Schema for creating an OU.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes |  |
| `description` | `string` \| `null` | no |  |
| `parent_id` | `string` \| `null` | no |  |
| `custom_attributes` | object \| `null` | no |  |

### `OUListItem`

Abbreviated OU info for lists.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `name` | `string` | yes |  |
| `path` | `string` | yes |  |
| `parent_id` | `string` \| `null` | no |  |
| `user_count` | `integer` | no | Default: `0` |

### `OUResponse`

Full OU response.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes |  |
| `description` | `string` \| `null` | no |  |
| `id` | `string` | yes |  |
| `path` | `string` | yes |  |
| `parent_id` | `string` \| `null` | no |  |
| `child_ou_count` | `integer` | no | Default: `0` |
| `user_count` | `integer` | no | Default: `0` |
| `children` | array of [`OUChildInfo`](#schema-ouchildinfo) \| `null` | no |  |
| `custom_attributes` | object \| `null` | no |  |
| `created_at` | `string` (`date-time`) | yes |  |
| `updated_at` | `string` (`date-time`) \| `null` | no |  |

### `OUTreeNode`

Tree node for OU hierarchy.

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | `string` | yes |  |
| `name` | `string` | yes |  |
| `path` | `string` | yes |  |
| `children` | array of [`OUTreeNode`](#schema-outreenode) \| `null` | no |  |

### `OUUpdate`

Schema for updating an OU.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` \| `null` | no |  |
| `description` | `string` \| `null` | no |  |
| `parent_id` | `string` \| `null` | no |  |
| `custom_attributes` | object \| `null` | no |  |

### `PaginatedResponse`

Paginated API response wrapper.

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array of _any_ | yes |  |
| `pagination` | [`PaginationMeta`](#schema-paginationmeta) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `PaginatedResponse_OUListItem_`

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | array of [`OUListItem`](#schema-oulistitem) | yes |  |
| `pagination` | [`PaginationMeta`](#schema-paginationmeta) | yes |  |
| `meta` | [`MetaResponse`](#schema-metaresponse) | no |  |

### `PaginationMeta`

Pagination metadata.

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | `integer` | yes |  |
| `per_page` | `integer` | yes |  |
| `total_items` | `integer` | yes |  |
| `total_pages` | `integer` | yes |  |

### `ValidationError`

| Field | Type | Required | Description |
|---|---|---|---|
| `loc` | array of `string` \| `integer` | yes |  |
| `msg` | `string` | yes |  |
| `type` | `string` | yes |  |