Folders API (2026.07-experimental)

Download OpenAPI specification:Download

API definitions for folder management capabilities in Adobe Experience Manager. To configure a client to access to these APIs, visit the Adobe Developer Console and add the "AEM Assets Author API" card or the "AEM CS Sites Content Management API" card to your project.

Folders

APIs for interacting with folders

List contents at the specified path

Returns the children of the folder specified by the path query parameter. By default, only child folders are returned. Use the types query parameter to include other resources in the listing. Results can be sorted using the orderBy query parameter.

SecurityBearer and ApiKeyHeader
Request
query Parameters
path
string non-empty
Default: "/"

Path of the folder from which to list the children.

Example: path=/content/dam/my-folder
limit
integer <int32> (Limit) [ 1 .. 50 ]

For a paginated request, this parameter defines the maximum number of items to retrieve.

cursor
string (Cursor) non-empty

When the number of results for a request exceeds the allowed limit, the response will include a cursor. That value can then be sent via this parameter on a subsequent request to retrieve the next set of items.

types
Array of strings (FolderListingItemType)
Default: ["FOLDER"]

Filter the listing by resource type. Accepts a comma-separated list of type values. When omitted, defaults to FOLDER only.

Items Enum: "FOLDER" "ASSET"
orderBy
string (OrderBy) non-empty

Sort order for listing results. Value is a comma-separated list of sort expressions. Each expression is a field name optionally followed by asc or desc (space-separated). Default direction is ascending when not specified.

Supported fields: name, size, lastModifiedAt.

Note: size and lastModifiedAt are only meaningful when the listing includes assets (types includes ASSET). When listing folders only, these sort fields are accepted but have no effect.

Example: orderBy=metadata.repositoryMetadata.repo:size desc,metadata.repositoryMetadata.repo:createDate asc
header Parameters
If-None-Match
string

The If-None-Match header field makes the request method conditional on a recipient cache or origin server either not having any current representation of the target resource, when the field value is "*", or having a selected representation with an entity tag that does not match any of those listed in the field value.

For more details, please head over to RFC9110.

Responses
200

List of children at the specified path

304

Not Modified

400

Bad Request. Indicates that the server cannot or will not process the request due to something that is perceived to be a client error. The Problem Details object will provide more information about the exact cause.

401

Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.

403

Forbidden. Indicates that the server understood the request but refuses to fulfil it.

404

Not Found. Indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.

406

Not Acceptable. Indicates that the target resource does not have a current representation that would be acceptable to the user agent, according to the proactive negotiation header fields received in the request.

get/
Request samples 
Response samples 
application/json
{
  • "self": {
    },
  • "children": [
    ]
}
Head request for listing contents at specified path
Returns headers, including an ETag for the specified folder path and listing query parameters


SecurityBearer and ApiKeyHeader 
Request 
query Parameters
path
string  non-empty 
 Default:  "/"
Path of the folder


 
 Example:  path=/content/dam/my-folder
limit
integer <int32>  (Limit)   [ 1 .. 50 ] 
For a paginated request, this parameter defines the maximum number of items to retrieve.


 
cursor
string (Cursor)   non-empty 
When the number of results for a request exceeds the allowed limit, the response will include a cursor.  That value can then be sent via this parameter on a subsequent request to retrieve the next set of items.


 
types
Array of strings (FolderListingItemType) 
 Default:  ["FOLDER"]
Filter the listing by resource type. Accepts a comma-separated list of type values.
When omitted, defaults to FOLDER only.


Items Enum: "FOLDER" "ASSET"  
orderBy
string (OrderBy)   non-empty 
Sort order for listing results. Value is a comma-separated list of sort expressions.
Each expression is a field name optionally followed by asc or desc (space-separated).
Default direction is ascending when not specified.


Supported fields: name, size, lastModifiedAt.


Note: size and lastModifiedAt are only meaningful when the listing includes assets
(types includes ASSET). When listing folders only, these sort fields are accepted
but have no effect.


 
 Example:  orderBy=metadata.repositoryMetadata.repo:size desc,metadata.repositoryMetadata.repo:createDate asc
header Parameters
If-None-Match
string
The If-None-Match header field makes the request method conditional on a recipient cache or origin server either
not having any current representation of the target resource, when the field value is "*", or having a selected
representation with an entity tag that does not match any of those listed in the field value.


For more details, please head over to RFC9110.


 
Responses 
200
OK


304
Not Modified


400
Bad Request.
Indicates that the server cannot or will not process the request due to something that is perceived to be a client error. The Problem Details object will provide more information about the exact cause.


401
Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.


403
Forbidden. Indicates that the server understood the request but refuses to fulfil it.


404
Not Found. Indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.


406
Not Acceptable.
Indicates that the target resource does not have a current representation that would be acceptable to the user agent,
according to the proactive negotiation header fields received in the request.


head/
Request samples 
Response samples 
application/problem+json
{}
Creates new folders at the specified paths.
One or more folder paths can be specified in the request body. The folders will be created at the specified
paths. If intermediate folders are missing, those will be created as well. This operation is limited to
batches of 10 folders. If the create operation requires more than a few seconds to complete, a job is created
and a status link is returned in the response's 'Location' header. Once the async job is complete, the status
link will return the results of the operation.


Accepted requests return HTTP 200 when completed synchronously, or HTTP 202 when processed asynchronously;
per-item outcomes are then reported in the command result body. A per-folder failure — including a conflict
when a folder already exists at the target path — is returned
in data.values.failedFolders[] (each item carries a problem type, e.g. .../errors/conflict). A conflict is
always reported per-item in data.values.failedFolders[], identified by path — never as a top-level errors[]
entry and never as an HTTP 409. As with the other batch operations, any failure that cannot be attributed to a
specific folder is reported in the top-level errors[].


SecurityBearer and ApiKeyHeader 
Request 
header Parameters
Prefer
string
The Prefer header field is used to indicate that particular server behaviors are preferred by the client, but
not required for successful completion of the request.  In the context of this API, the following preferences
are supported:


    

  • respond-async: Indicates that the client prefers an asynchronous response for operations that may take a long
time to complete.
    • 

  • wait: Establishes an upper bound on the length of time, in seconds, the client expects it will take the server
to process the request once it has been received. The server can choose to utilize an asynchronous processing
model (e.g., returning a 202 Accepted response) if processing will take longer than the specified time. wait
needs to be sent together with respond-async, for example respond-async, wait=10.
    • 



For more details, please refer to RFC 7240.


  Examples: 
Prefer an asynchronous response. 
respond-async
Prefer an asynchronous response but wait for up to 10 seconds for the server to process the request synchronously. 
respond-async, wait=10
Request Body schema: application/json
 Array (<= 10 items)
path
required
string  non-empty 
The path of the folder to be created


 
title
string
The title of the folder to be created


 
Responses 
200
Create-folders command result. Per-item outcomes are reported in the body. Conflicts (a folder already exists) are returned in data.values.failedFolders[], not as an HTTP 409.


202
Accepted


400
Bad Request.
Indicates that the server cannot or will not process the request due to something that is perceived to be a client error. The Problem Details object will provide more information about the exact cause.


401
Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.


403
Forbidden. Indicates that the server understood the request but refuses to fulfil it.


406
Not Acceptable.
Indicates that the target resource does not have a current representation that would be acceptable to the user agent,
according to the proactive negotiation header fields received in the request.


post/
Request samples 
application/json
[
  • {
    }
]
Response samples 
application/json
{
  • "operation": "adobe.folders.createFolders",
  • "status": 200,
  • "description": "Created folders",
  • "data": {
    },
  • "errors": [ ],
  • "warnings": [ ]
}
Delete folder(s) by path
The folders with the specified paths will be deleted. If the delete operation requires more than a few
seconds to complete, a job is created and a status link is returned in the response's 'Location' header. Once
the async job is complete, the status link will return the results of the operation.


Per-item outcomes are reported in the body. A per-folder failure is returned in data.failedFolders[] (each
item carries a problem type, e.g. .../errors/conflict); failures that cannot be tied to a specific folder
appear in the top-level errors[]. Conflicts are NOT surfaced as an HTTP 409.


SecurityBearer and ApiKeyHeader 
Request 
Request Body schema: application/json
paths
required
Array of strings  <= 10 items  unique 
The paths of the folders to be deleted.


 
recursive
boolean
If true, delete the directory and all descendants


 
force
boolean
If true, delete the directory even if it is referenced


 
Responses 
200
Delete-folders command result. Per-item outcomes are reported in the body. A per-folder failure is returned in data.failedFolders[]; failures that cannot be tied to a specific folder appear in top-level errors[]. These per-item failures are NOT surfaced as HTTP error statuses (request-level errors such as 400/401/403/404/406 still apply).


202
Accepted


400
Bad Request.
Indicates that the server cannot or will not process the request due to something that is perceived to be a client error. The Problem Details object will provide more information about the exact cause.


401
Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.


403
Forbidden. Indicates that the server understood the request but refuses to fulfil it.


404
Not Found. Indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.


406
Not Acceptable.
Indicates that the target resource does not have a current representation that would be acceptable to the user agent,
according to the proactive negotiation header fields received in the request.


post/delete
Request samples 
application/json
{
  • "paths": [
    ],
  • "recursive": true,
  • "force": true
}
Response samples 
application/json
{
  • "operation": "adobe.folders.deleteFolders",
  • "status": 200,
  • "description": "No folders were deleted.",
  • "data": {},
  • "errors": [ ],
  • "warnings": [ ]
}
Head request for listing contents under the specified folder ID
Returns headers, including an ETag for the specified folder contents listing, which can be a lighter method of checking for the existence of, or validating a cached version of a folder's contents without sending a full GET request.


SecurityBearer and ApiKeyHeader 
Request 
path Parameters
folderId
required
string  non-empty 
ID of the folder to access


  Examples: 
urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
query Parameters
limit
integer <int32>  (Limit)   [ 1 .. 50 ] 
For a paginated request, this parameter defines the maximum number of items to retrieve.


 
cursor
string (Cursor)   non-empty 
When the number of results for a request exceeds the allowed limit, the response will include a cursor.  That value can then be sent via this parameter on a subsequent request to retrieve the next set of items.


 
types
Array of strings (FolderListingItemType) 
 Default:  ["FOLDER"]
Filter the listing by resource type. Accepts a comma-separated list of type values.
When omitted, defaults to FOLDER only.


Items Enum: "FOLDER" "ASSET"  
orderBy
string (OrderBy)   non-empty 
Sort order for listing results. Value is a comma-separated list of sort expressions.
Each expression is a field name optionally followed by asc or desc (space-separated).
Default direction is ascending when not specified.


Supported fields: name, size, lastModifiedAt.


Note: size and lastModifiedAt are only meaningful when the listing includes assets
(types includes ASSET). When listing folders only, these sort fields are accepted
but have no effect.


 
 Example:  orderBy=metadata.repositoryMetadata.repo:size desc,metadata.repositoryMetadata.repo:createDate asc
header Parameters
If-None-Match
string
The If-None-Match header field makes the request method conditional on a recipient cache or origin server either
not having any current representation of the target resource, when the field value is "*", or having a selected
representation with an entity tag that does not match any of those listed in the field value.


For more details, please head over to RFC9110.


 
Responses 
200
OK


304
Not Modified


400
Bad Request.
Indicates that the server cannot or will not process the request due to something that is perceived to be a client error. The Problem Details object will provide more information about the exact cause.


401
Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.


403
Forbidden. Indicates that the server understood the request but refuses to fulfil it.


404
Not Found. Indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.


406
Not Acceptable.
Indicates that the target resource does not have a current representation that would be acceptable to the user agent,
according to the proactive negotiation header fields received in the request.


head/{folderId}
Request samples 
Response samples 
application/problem+json
{}
List contents under the specified folder ID
Returns the children of the specified folder. By default, only child folders are returned.
Use the types query parameter to include other resources in the listing.
Results can be sorted using the orderBy query parameter.


SecurityBearer and ApiKeyHeader 
Request 
path Parameters
folderId
required
string  non-empty 
ID of the folder to access


  Examples: 
urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
query Parameters
limit
integer <int32>  (Limit)   [ 1 .. 50 ] 
For a paginated request, this parameter defines the maximum number of items to retrieve.


 
cursor
string (Cursor)   non-empty 
When the number of results for a request exceeds the allowed limit, the response will include a cursor.  That value can then be sent via this parameter on a subsequent request to retrieve the next set of items.


 
types
Array of strings (FolderListingItemType) 
 Default:  ["FOLDER"]
Filter the listing by resource type. Accepts a comma-separated list of type values.
When omitted, defaults to FOLDER only.


Items Enum: "FOLDER" "ASSET"  
orderBy
string (OrderBy)   non-empty 
Sort order for listing results. Value is a comma-separated list of sort expressions.
Each expression is a field name optionally followed by asc or desc (space-separated).
Default direction is ascending when not specified.


Supported fields: name, size, lastModifiedAt.


Note: size and lastModifiedAt are only meaningful when the listing includes assets
(types includes ASSET). When listing folders only, these sort fields are accepted
but have no effect.


 
 Example:  orderBy=metadata.repositoryMetadata.repo:size desc,metadata.repositoryMetadata.repo:createDate asc
header Parameters
If-None-Match
string
The If-None-Match header field makes the request method conditional on a recipient cache or origin server either
not having any current representation of the target resource, when the field value is "*", or having a selected
representation with an entity tag that does not match any of those listed in the field value.


For more details, please head over to RFC9110.


 
Responses 
200
List of children under the specified folder ID


304
Not Modified


400
Bad Request.
Indicates that the server cannot or will not process the request due to something that is perceived to be a client error. The Problem Details object will provide more information about the exact cause.


401
Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.


403
Forbidden. Indicates that the server understood the request but refuses to fulfil it.


404
Not Found. Indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.


406
Not Acceptable.
Indicates that the target resource does not have a current representation that would be acceptable to the user agent,
according to the proactive negotiation header fields received in the request.


get/{folderId}
Request samples 
Response samples 
application/json
{
  • "self": {
    },
  • "children": [
    ]
}
Delete folder by its ID
The folder with the specified ID will be deleted. If the delete operation requires more than a few seconds to complete, a job is created and a status link is returned in the response header that can be used to check the status.


SecurityBearer and ApiKeyHeader 
Request 
path Parameters
folderId
required
string  non-empty 
ID of the folder to access


  Examples: 
urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
query Parameters
recursive
boolean
If true, delete the directory and all descendants


 
force
boolean
If true, delete the directory even if it is referenced


 
Responses 
200
Folder deleted successfully


202
Accepted


400
Bad Request.
Indicates that the server cannot or will not process the request due to something that is perceived to be a client error. The Problem Details object will provide more information about the exact cause.


401
Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.


403
Forbidden. Indicates that the server understood the request but refuses to fulfil it.


404
Not Found. Indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.


406
Not Acceptable.
Indicates that the target resource does not have a current representation that would be acceptable to the user agent,
according to the proactive negotiation header fields received in the request.


delete/{folderId}
Request samples 
Response samples 
application/json
{
  • "operation": "adobe.folders.deleteFolders",
  • "status": 200,
  • "description": "Some folders have been deleted; others failed.",
  • "data": {}
}
Get the status of an async job
Retrieves the current status of a job created by the folder API.


SecurityBearer and ApiKeyHeader 
Request 
path Parameters
jobId
required
string <uuid> 
ID of a backend asynchronous job


  Examples: 
542c88b4-e136-4341-9221-ae42d3d70b10
Responses 
200
Status of a job being processed


303
The job has finished executing and results are available at the indicated location.


400
Bad Request.
Indicates that the server cannot or will not process the request due to something that is perceived to be a client error. The Problem Details object will provide more information about the exact cause.


401
Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.


403
Forbidden. Indicates that the server understood the request but refuses to fulfil it.


404
Not Found. Indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.


406
Not Acceptable.
Indicates that the target resource does not have a current representation that would be acceptable to the user agent,
according to the proactive negotiation header fields received in the request.


get/jobs/{jobId}/status
Request samples 
Response samples 
application/json
{
  • "jobId": "85f7c90a-a252-4e82-8cf3-3c989829cdf9",
  • "state": "PROCESSING"
}
Get the results of a completed job
Retrieves the current status of a job created by the folder API.


SecurityBearer and ApiKeyHeader 
Request 
path Parameters
jobId
required
string <uuid> 
ID of a backend asynchronous job


  Examples: 
542c88b4-e136-4341-9221-ae42d3d70b10
Responses 
200
The results of the completed or failed async job.


400
Bad Request.
Indicates that the server cannot or will not process the request due to something that is perceived to be a client error. The Problem Details object will provide more information about the exact cause.


401
Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.


403
Forbidden. Indicates that the server understood the request but refuses to fulfil it.


404
Not Found. Indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.


406
Not Acceptable.
Indicates that the target resource does not have a current representation that would be acceptable to the user agent,
according to the proactive negotiation header fields received in the request.


get/jobs/{jobId}/result
Request samples 
Response samples 
application/json
{
  • "operation": "adobe.folders.createFolders",
  • "status": 200,
  • "description": "Some folders have been created; others failed.",
  • "data": {
    }
}