# Folders

Source: https://docs.elnora.ai/docs/api/reference/folders
Last modified: 2026-09-14T10:17:43-06:00

> Folders endpoints of the Elnora REST API.

Base URL `https://platform.elnora.ai/api/v1`. Authenticate every request with the `X-API-Key` header — see [Authentication](https://docs.elnora.ai/docs/get-started/authentication).

## `POST` /folders

Create a folder under a parent the caller can write to.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "...", "visibility": "..." }'
```

**Request body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `parentFolderId` | uuid | no |
| `visibility` | string | yes |
| `kind` | string | no |

**Responses**: `201` · `400` · `403`

## `GET` /folders/{id}

Folder metadata plus breadcrumbs (root → folder), walked via the closure table.

```bash
curl https://platform.elnora.ai/api/v1/folders/{id} \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Responses**: `200` · `403` · `404`

## `PATCH` /folders/{id}

Rename and/or move a folder.

```bash
curl -X PATCH https://platform.elnora.ai/api/v1/folders/{id} \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Request body**

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | no |
| `parentFolderId` | uuid | no |
| `moveToRoot` | boolean | no |

**Responses**: `200` · `400` · `403` · `404`

## `GET` /folders/{id}/access

"Who has access" (KB Sharing v3): the full EFFECTIVE access list for a folder — every principal who can reach it, each labelled direct (granted on this folder) or inherited (cascaded from an ancestor).

```bash
curl https://platform.elnora.ai/api/v1/folders/{id}/access \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Responses**: `200` · `403`

## `POST` /folders/{id}/archive

Soft-delete (archive) a folder.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/{id}/archive \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Responses**: `204` · `403` · `404`

## `POST` /folders/{id}/break-inheritance

Stops a folder from inheriting ACEs from its ancestor scope, copying the currently-effective ACEs onto the folder first.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/{id}/break-inheritance \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Responses**: `204` · `403` · `404`

## `GET` /folders/{id}/children

Direct children of id visible to the current user.

```bash
curl https://platform.elnora.ai/api/v1/folders/{id}/children \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Responses**: `200` · `403`

## `GET` /folders/{id}/contained-overrides

Warn-on-narrow (KB Sharing v3): files inside this folder that are shared MORE widely than the folder — they carry their own share that would survive a narrowing.

```bash
curl https://platform.elnora.ai/api/v1/folders/{id}/contained-overrides \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Responses**: `200` · `403`

## `GET` /folders/{id}/files

Paged list of files directly placed under workspace-model folder id.

```bash
curl https://platform.elnora.ai/api/v1/folders/{id}/files \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |
| `page` | query | int32 | no |
| `pageSize` | query | int32 | no |

**Responses**: `200` · `403`

## `POST` /folders/{id}/files/upload

Initiate a single file upload into the workspace-model folder id.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/{id}/files/upload \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileName": "...", "contentType": "...", "fileSizeBytes": "..." }'
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Request body**

| Field | Type | Required |
| --- | --- | --- |
| `fileName` | string | yes |
| `contentType` | string | yes |
| `fileSizeBytes` | int64 | yes |
| `taskId` | uuid | no |

**Responses**: `200` · `400` · `403`

## `POST` /folders/{id}/files/upload/batch

Batch initiate uploads for multiple files (max 50) all landing under the workspace-model folder id.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/{id}/files/upload/batch \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "items": [] }'
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Request body**

| Field | Type | Required |
| --- | --- | --- |
| `items` | InitiateFolderUpload[] | yes |

**Responses**: `200` · `400` · `403`

## `PATCH` /folders/{id}/move

Dedicated folder-reparent endpoint backing the workspace tree's drag-and-drop UX.

```bash
curl -X PATCH https://platform.elnora.ai/api/v1/folders/{id}/move \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Request body**

| Field | Type | Required |
| --- | --- | --- |
| `parentFolderId` | uuid | no |

**Responses**: `200` · `400` · `403` · `404`

## `POST` /folders/{id}/narrow-cascade

Explicit, previewed narrow-cascade (KB Sharing v3): clears the audience-widening shares on the listed contained files.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/{id}/narrow-cascade \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Request body**

| Field | Type | Required |
| --- | --- | --- |
| `fileIds` | uuid[] | no |

**Responses**: `200` · `403`

## `POST` /folders/{id}/restore

Restore an archived folder and its subtree — the inverse of Write access is enforced inside; the tenant guard runs first.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/{id}/restore \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Responses**: `200` · `403` · `404`

## `POST` /folders/{id}/share

Adds a folder ACE.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/{id}/share \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "..." }'
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Request body**

| Field | Type | Required |
| --- | --- | --- |
| `userId` | int32 | no |
| `teamId` | uuid | no |
| `isOrgWide` | boolean | no |
| `role` | string | yes |

**Responses**: `201` · `400` · `403` · `404`

## `DELETE` /folders/{id}/share/{aceId}

Removes a folder ACE by id.

```bash
curl -X DELETE https://platform.elnora.ai/api/v1/folders/{id}/share/{aceId} \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |
| `aceId` | path | uuid | yes |

**Responses**: `204` · `403` · `404`

## `GET` /folders/{id}/shares

List the current shares on a folder (with resolved principal name/email).

```bash
curl https://platform.elnora.ai/api/v1/folders/{id}/shares \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id` | path | uuid | yes |

**Responses**: `200` · `403`

## `GET` /folders/archived

The caller's readable archived folders (top of each archived subtree), newest first — the trash view that makes reachable from the product .

```bash
curl https://platform.elnora.ai/api/v1/folders/archived \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Responses**: `200`

## `POST` /folders/drafts-user

Eagerly seed the per-user drafts folder `uploads/<U>/_drafts/` for the CURRENT user and return its id.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/drafts-user \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json"
```

**Responses**: `200` · `400` · `401`

## `POST` /folders/ensure-user-kb-folder

Eagerly seed the per-user personal subfolder `knowledge-base/<DisplayName>/` for the CURRENT user and return both the user-folder id and the KB root id.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/ensure-user-kb-folder \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

**Request body**

| Field | Type | Required |
| --- | --- | --- |
| `displayName` | string | no |

**Responses**: `200` · `400` · `401`

## `GET` /folders/files

Flat list of files visible to the current user across every folder in the active organization.

```bash
curl https://platform.elnora.ai/api/v1/folders/files \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `q` | query | string | no |

**Responses**: `200`

## `GET` /folders/roots

Top-level folders in the current user's organization that the user can read.

```bash
curl https://platform.elnora.ai/api/v1/folders/roots \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Responses**: `200`

## `GET` /folders/sharing-drift

Org sharing-drift report (KB Sharing v3, ): files whose audience is wider than their folder, org-wide.

```bash
curl https://platform.elnora.ai/api/v1/folders/sharing-drift \
  -H "X-API-Key: $ELNORA_API_KEY"
```

**Responses**: `200` · `403`

## `POST` /folders/uploads-task/{taskId}

Eagerly seed the per-task uploads folder `uploads/<U>/<taskId>/` for the CURRENT user and return its id.

```bash
curl -X POST https://platform.elnora.ai/api/v1/folders/uploads-task/{taskId} \
  -H "X-API-Key: $ELNORA_API_KEY" \
  -H "Content-Type: application/json"
```

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `taskId` | path | uuid | yes |

**Responses**: `200` · `400` · `401`