---
canonical: https://amplience.com/developers/docs/apis/content-management-reference/folders-hierarchy/
title: "Folders and hierarchy"
description: "API reference for folder and hierarchy endpoints. Covers folder management within repositories and hierarchy node operations."
audience: Developer
date_published: 2023-08-29
date_modified: 2026-06-16
---

# Folders and hierarchy

**Base URL:** `https://api.amplience.net/v2/content`

> **Note: Authorization and status codes**
> For authorization and status codes see the [API Reference overview](https://amplience.com/developers/docs/apis/content-management-reference/).

## Folders

| Method | Endpoint | Summary |
|--------|----------|---------|
| `POST` | `/content-repositories/{contentRepositoryId}/folders` | [Create folder](#create-folder) |
| `GET` | `/content-repositories/{contentRepositoryId}/folders` | [List folders](#list-folders) |
| `PATCH` | `/folders/{folderId}` | [Update folder](#update-folder) |
| `GET` | `/folders/{folderId}` | [Get folder](#get-folder) |
| `DELETE` | `/folders/{folderId}` | [Delete folder](#delete-folder) |
| `POST` | `/folders/{folderId}/folders` | [Create sub-folder](#create-sub-folder) |
| `GET` | `/folders/{folderId}/folders` | [List sub-folders](#list-sub-folders) |

### Create folder

`POST /content-repositories/{contentRepositoryId}/folders`

<small>`https://api.amplience.net/v2/content/content-repositories/{contentRepositoryId}/folders`</small>

Folders are used to organise items in a hierarchical structure. Currently only enabled for organising content items within a content repository.

To create a new folder follow the "create-folder" link from a content repository.

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `contentRepositoryId` | path | string | ✓ | Content Repository ID<br/>Example: `00112233445566778899aabb` |

**Request Body**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | ✓ | Folder name |

<details>
<summary>Request example</summary>

```json
{
  "name": "New folder"
}
```

</details>

**Responses**

| Status | Description |
|--------|-------------|
| 201 | Created Content Repository Folder |

<details>
<summary>Response Example (201)</summary>

```json
{
  "id": "00112233445566778899aabb",
  "name": "New folder",
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "content-repository": {
      "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb"
    },
    "content-items": {
      "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb/content-items?folderId=00112233445566778899aabb{&page,projection,size,sort,status}",
      "templated": true
    },
    "create-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb/folders"
    },
    "delete-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "update-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    }
  }
}
```

</details>

### List folders

`GET /content-repositories/{contentRepositoryId}/folders`

<small>`https://api.amplience.net/v2/content/content-repositories/{contentRepositoryId}/folders`</small>

List all of the top-level Folders for a Content Repository

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `contentRepositoryId` | path | string | ✓ | Content Repository ID<br/>Example: `00112233445566778899aabb` |
| `page` | query | integer |  | Page number<br/>Example: `0` |
| `size` | query | integer |  | Page size<br/>Example: `20` |
| `sort` | query | string |  | Sort paramter<br/>Example: `createdDate,asc` |

**Responses**

| Status | Description |
|--------|-------------|
| 200 | Top-level Folders |

<details>
<summary>Response Example (200)</summary>

```json
{
  "_embedded": {
    "folders": [
      {
        "id": "00112233445566778899aabb",
        "name": "New folder",
        "_links": {
          "self": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
          },
          "folder": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
          },
          "content-repository": {
            "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb"
          },
          "content-items": {
            "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb/content-items?folderId=00112233445566778899aabb{&page,projection,size,sort,status}",
            "templated": true
          },
          "create-folder": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb/folders"
          },
          "delete-folder": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
          },
          "update-folder": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/content-repositories/5d5bc1dfc9e77c035fede5c7/folders?page=0&size=20"
    },
    "first": {
      "href": "https://api.amplience.net/v2/content/content-repositories/5d5bc1dfc9e77c035fede5c7/folders?page=0&size=20"
    },
    "last": {
      "href": "https://api.amplience.net/v2/content/content-repositories/5d5bc1dfc9e77c035fede5c7/folders?page=0&size=20"
    },
    "search": {
      "href": "https://api.amplience.net/v2/content/content-repositories/5d5bc1dfc9e77c035fede5c7/folders/search"
    }
  },
  "page": {
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "number": 0
  }
}
```

</details>

### Update folder

`PATCH /folders/{folderId}`

<small>`https://api.amplience.net/v2/content/folders/{folderId}`</small>

Update a folder

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `folderId` | path | string | ✓ | Folder ID<br/>Example: `00112233445566778899aabb` |

**Request Body**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string |  | Folder name |

<details>
<summary>Request example</summary>

```json
{
  "name": "New folder"
}
```

</details>

**Responses**

| Status | Description |
|--------|-------------|
| 200 | Updated Folder |

<details>
<summary>Response Example (200)</summary>

```json
{
  "id": "00112233445566778899aabb",
  "name": "New folder",
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "content-repository": {
      "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb"
    },
    "content-items": {
      "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb/content-items?folderId=00112233445566778899aabb{&page,projection,size,sort,status}",
      "templated": true
    },
    "create-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb/folders"
    },
    "delete-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "update-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    }
  }
}
```

</details>

### Get folder

`GET /folders/{folderId}`

<small>`https://api.amplience.net/v2/content/folders/{folderId}`</small>

Get a folder

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `folderId` | path | string | ✓ | Folder ID<br/>Example: `00112233445566778899aabb` |

**Responses**

| Status | Description |
|--------|-------------|
| 200 | Folder |

<details>
<summary>Response Example (200)</summary>

```json
{
  "id": "00112233445566778899aabb",
  "name": "New folder",
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "content-repository": {
      "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb"
    },
    "content-items": {
      "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb/content-items?folderId=00112233445566778899aabb{&page,projection,size,sort,status}",
      "templated": true
    },
    "create-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb/folders"
    },
    "delete-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "update-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    }
  }
}
```

</details>

### Delete folder

`DELETE /folders/{folderId}`

<small>`https://api.amplience.net/v2/content/folders/{folderId}`</small>

Delete a folder

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `folderId` | path | string | ✓ | Folder ID<br/>Example: `00112233445566778899aabb` |

**Responses**

| Status | Description |
|--------|-------------|
| 204 | Success |

### Create sub-folder

`POST /folders/{folderId}/folders`

<small>`https://api.amplience.net/v2/content/folders/{folderId}/folders`</small>

Create a new sub-folder.

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `contentRepositoryId` | path | string | ✓ | Content Repository ID<br/>Example: `00112233445566778899aabb` |

**Request Body**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | ✓ | Folder name |

<details>
<summary>Request example</summary>

```json
{
  "name": "New folder"
}
```

</details>

**Responses**

| Status | Description |
|--------|-------------|
| 201 | Created Sub-Folder |

<details>
<summary>Response Example (201)</summary>

```json
{
  "id": "00112233445566778899aabb",
  "name": "New folder",
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "content-repository": {
      "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb"
    },
    "content-items": {
      "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb/content-items?folderId=00112233445566778899aabb{&page,projection,size,sort,status}",
      "templated": true
    },
    "create-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb/folders"
    },
    "delete-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    },
    "update-folder": {
      "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
    }
  }
}
```

</details>

### List sub-folders

`GET /folders/{folderId}/folders`

<small>`https://api.amplience.net/v2/content/folders/{folderId}/folders`</small>

List the sub-folders of a folder

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `folderId` | path | string | ✓ | Folder ID<br/>Example: `00112233445566778899aabb` |

**Responses**

| Status | Description |
|--------|-------------|
| 200 | Folder |

<details>
<summary>Response Example (200)</summary>

```json
{
  "_embedded": {
    "folders": [
      {
        "id": "00112233445566778899aabb",
        "name": "New folder",
        "_links": {
          "self": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
          },
          "folder": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
          },
          "content-repository": {
            "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb"
          },
          "content-items": {
            "href": "https://api.amplience.net/v2/content/content-repositories/00112233445566778899aabb/content-items?folderId=00112233445566778899aabb{&page,projection,size,sort,status}",
            "templated": true
          },
          "create-folder": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb/folders"
          },
          "delete-folder": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
          },
          "update-folder": {
            "href": "https://api.amplience.net/v2/content/folders/00112233445566778899aabb"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/content-repositories/5d5bc1dfc9e77c035fede5c7/folders?page=0&size=20"
    },
    "first": {
      "href": "https://api.amplience.net/v2/content/content-repositories/5d5bc1dfc9e77c035fede5c7/folders?page=0&size=20"
    },
    "last": {
      "href": "https://api.amplience.net/v2/content/content-repositories/5d5bc1dfc9e77c035fede5c7/folders?page=0&size=20"
    },
    "search": {
      "href": "https://api.amplience.net/v2/content/content-repositories/5d5bc1dfc9e77c035fede5c7/folders/search"
    }
  },
  "page": {
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "number": 0
  }
}
```

</details>

## Hierarchy node

| Method | Endpoint | Summary |
|--------|----------|---------|
| `GET` | `/hierarchy-node/{id}/children` | [Get child hierarchy nodes](#get-child-hierarchy-nodes) |
| `GET` | `/hierarchy-node/{id}/parents` | [Get parent hierarchy nodes](#get-parent-hierarchy-nodes) |
| `POST` | `/hierarchy-node/{id}/position` | [Change a hierarchy node's position](#change-a-hierarchy-nodes-position) |

### Get child hierarchy nodes

`GET /hierarchy-node/{id}/children`

<small>`https://api.amplience.net/v2/content/hierarchy-node/{id}/children`</small>

Get a List of Child Hierarchy Nodes

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `contentItemId` | path | string | ✓ | Content Item ID<br/>Example: `00112233-4455-6677-8899-aabbccddeeff` |

**Responses**

| Status | Description |
|--------|-------------|
| 200 | List of Child Hierarchy Nodes |

<details>
<summary>Response Example (200)</summary>

```json
{
  "id": "00112233-4455-6677-8899-aabbccddeeff",
  "label": "Banner Ad Homepage",
  "root": true,
  "children": [
    {
      "id": "00112233-4455-6677-8899-aabbccddeeff",
      "label": "Banner Ad Homepage",
      "root": false,
      "parentId": "00112233-4455-6677-8899-aabbccddeeff",
      "_links": {
        "content-item": {
          "href": "https://api.amplience.net/v2/content/content-items/00112233-4455-6677-8899-aabbccddeeff"
        },
        "archive": {
          "href": "https://api.amplience.net/v2/content/content-items/00112233-4455-6677-8899-aabbccddeeff/archive"
        },
        "get-hierarchy-parents": {
          "href": "https://api.amplience.net/v2/content/hierarchy-node/00112233-4455-6677-8899-aabbccddeeff/parents"
        },
        "get-hierarchy-children": {
          "href": "https://api.amplience.net/v2/content/hierarchy-node/00112233-4455-6677-8899-aabbccddeeff/children"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/hierarchy-node/00112233-4455-6677-8899-aabbccddeeff/children"
    },
    "content-item": {
      "href": "https://api.amplience.net/v2/content/content-items/00112233-4455-6677-8899-aabbccddeeff"
    }
  }
}
```

</details>

### Get parent hierarchy nodes

`GET /hierarchy-node/{id}/parents`

<small>`https://api.amplience.net/v2/content/hierarchy-node/{id}/parents`</small>

Get a List of Parent Hierarchy Nodes

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `contentItemId` | path | string | ✓ | Content Item ID<br/>Example: `00112233-4455-6677-8899-aabbccddeeff` |

**Responses**

| Status | Description |
|--------|-------------|
| 200 | List of Parent Hierarchy Nodes |

<details>
<summary>Response Example (200)</summary>

```json
{
  "id": "00112233-4455-6677-8899-aabbccddeeff",
  "label": "Banner Ad Homepage",
  "root": false,
  "parents": [
    {
      "id": "00112233-4455-6677-8899-aabbccddeeff",
      "label": "Banner Ad Homepage",
      "root": true,
      "_links": {
        "content-item": {
          "href": "https://api.amplience.net/v2/content/content-items/00112233-4455-6677-8899-aabbccddeeff"
        },
        "archive": {
          "href": "https://api.amplience.net/v2/content/content-items/00112233-4455-6677-8899-aabbccddeeff/archive"
        },
        "get-hierarchy-parents": {
          "href": "https://api.amplience.net/v2/content/hierarchy-node/00112233-4455-6677-8899-aabbccddeeff/parents"
        },
        "get-hierarchy-children": {
          "href": "https://api.amplience.net/v2/content/hierarchy-node/00112233-4455-6677-8899-aabbccddeeff/children"
        }
      }
    }
  ],
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/hierarchy-node/00112233-4455-6677-8899-aabbccddeeff/parents"
    },
    "content-item": {
      "href": "https://api.amplience.net/v2/content/content-items/00112233-4455-6677-8899-aabbccddeeff"
    }
  }
}
```

</details>

### Change a hierarchy node's position

`POST /hierarchy-node/{id}/position`

<small>`https://api.amplience.net/v2/content/hierarchy-node/{id}/position`</small>

Change a Hierarchy Node's position

**Parameters**

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `contentItemId` | path | string | ✓ | Content Item ID<br/>Example: `00112233-4455-6677-8899-aabbccddeeff` |

**Responses**

| Status | Description |
|--------|-------------|
| 200 | List of Hierarchy Node Position Changes |

## Hierarchies publish

| Method | Endpoint | Summary |
|--------|----------|---------|
| `POST` | `/hierarchies/publish` | [Publish hierarchy nodes](#publish-hierarchy-nodes) |

### Publish hierarchy nodes

`POST /hierarchies/publish`

<small>`https://api.amplience.net/v2/content/hierarchies/publish`</small>

To publish a hierarchy tree, you need to specify the root node and set getDescendants to true.

To publish a hierarchy branch, you need to specify the parent node and set getDescendants to true.

To publish a hierarchy node without any children and set getDescendants to false.

To publish multiple nodes individually supply their IDs, you cannot publish multiple nodes with getDescendants set to true.

**Request Body**

Content-Type: `application/json`

<details>
<summary>Request example</summary>

```json
[
  {
    "hierarchyNodeIds": [
      "00112233-4455-6677-8899-aabbccddeeff"
    ],
    "getDescendants": false
  }
]
```

</details>

**Responses**

| Status | Description |
|--------|-------------|
| 204 | No Content |

## Hierarchies snapshot

| Method | Endpoint | Summary |
|--------|----------|---------|
| `POST` | `/hierarchies/snapshot` | [Snapshot hierarchy nodes](#snapshot-hierarchy-nodes) |

### Snapshot hierarchy nodes

`POST /hierarchies/snapshot`

<small>`https://api.amplience.net/v2/content/hierarchies/snapshot`</small>

To snapshot a hierarchy tree, you need to specify the root node and set getDescendants to true.

To snapshot a hierarchy branch, you need to specify the parent node and set getDescendants to true.

To snapshot a hierarchy node without any children and set getDescendants to false.

To snapshot multiple nodes individually supply their IDs, you cannot snapshot multiple nodes with getDescendants set to true.

**Request Body**

Content-Type: `application/json`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hierarchyNodeIds` | array |  | ID's |
| `getDescendants` | boolean |  |  |
| `type` | string (USER, SYSTEM) |  | Indicates the type of Snapshot (USER or SYSTEM) |
| `comment` | string |  | Comment |

<details>
<summary>Request example</summary>

```json
{
  "hierarchyNodeIds": [
    "00112233-4455-6677-8899-aabbccddeeff"
  ],
  "getDescendants": false,
  "comment": "This is a example snapshot."
}
```

</details>

**Responses**

| Status | Description |
|--------|-------------|
| 201 | Snapshot |

<details>
<summary>Response Example (201)</summary>

```json
{
  "id": "00112233445566778899aabb",
  "comment": "This is a example snapshot.",
  "createdDate": "2019-01-01T00:00:00.000Z",
  "createdBy": "00112233-4455-6677-8899-aabbccddeeff",
  "createdFrom": "content-item",
  "type": "USER",
  "meta": [
    {
      "key": "example-key",
      "value": "example value"
    }
  ],
  "taggedEdition": [
    {
      "editionId": "00112233445566778899aabb",
      "createdDate": "2019-01-01T00:00:00.000Z",
      "createdBy": "00112233-4455-6677-8899-aabbccddeeff",
      "name": "Example Edition 1",
      "editionName": "Example Edition 1"
    }
  ],
  "locale": "en-US",
  "contentRoot": "00112233-4455-6677-8899-aabbccddeeff",
  "rootContentItem": {
    "label": "Banner Ad Homepage",
    "contentTypeUri": "Banner Ad Homepage",
    "id": "00112233-4455-6677-8899-aabbccddeeff"
  },
  "rootContentItems": [
    {
      "label": "Banner Ad Homepage",
      "contentTypeUri": "Banner Ad Homepage",
      "id": "00112233-4455-6677-8899-aabbccddeeff"
    }
  ],
  "_links": {
    "self": {
      "href": "https://api.amplience.net/v2/content/snapshots/00112233445566778899aabb"
    },
    "snapshot": {
      "href": "https://api.amplience.net/v2/content/snapshots/00112233445566778899aabb"
    },
    "publishing-jobs": {
      "href": "https://api.amplience.net/v2/content/snapshots/00112233445566778899aabb/publishing-jobs{?page,size,sort}",
      "templated": true
    },
    "create-publishing-job": {
      "href": "https://api.amplience.net/v2/content/snapshots/00112233445566778899aabb/publishing-jobs"
    },
    "edition-links": {
      "href": "https://api.amplience.net/v2/content/snapshots/00112233445566778899aabb/edition-links"
    },
    "hub": {
      "href": "https://api.amplience.net/v2/content/hubs/00112233445566778899aabb"
    },
    "content-root": {
      "href": "https://api.amplience.net/v2/content/content-items/00112233445566778899aabb"
    },
    "snapshot-content-item": {
      "href": "https://api.amplience.net/v2/content/snapshots/00112233445566778899aabb/content-items{/id}",
      "templated": true
    }
  }
}
```

</details>