openapi: 3.0.3
info:
  title: Folders API
  description: 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.
  version: '2026.07'
servers:
  - url: https://{bucket}.adobeaemcloud.com/adobe/folders
    variables:
      bucket:
        default: ''
        description: The bucket to use for this request, e.g. author-p12345-e123456
security:
  - bearerAuth: []
tags:
  - name: Folders
    description: APIs for interacting with folders
paths:
  /:
    get:
      summary: List contents at the specified path
      description: |
        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.
      operationId: getFoldersByPath
      security:
        - Bearer: []
          ApiKeyHeader: []
      tags:
        - Folders
      parameters:
        - $ref: '#/components/parameters/If-None-Match'
        - in: query
          name: path
          description: |
            Path of the folder from which to list the children.
          schema:
            type: string
            minLength: 1
            default: /
            example: /content/dam/my-folder
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/Types'
        - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: List of children at the specified path
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderListing'
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304_NotModified'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '403':
          $ref: '#/components/responses/403_Forbidden'
        '404':
          $ref: '#/components/responses/404_NotFound'
        '406':
          $ref: '#/components/responses/406_Unacceptable'
    head:
      summary: Head request for listing contents at specified path
      description: Returns headers, including an ETag for the specified folder path and listing query parameters
      operationId: headFoldersByPath
      security:
        - Bearer: []
          ApiKeyHeader: []
      tags:
        - Folders
      parameters:
        - $ref: '#/components/parameters/If-None-Match'
        - in: query
          name: path
          description: Path of the folder
          schema:
            type: string
            minLength: 1
            default: /
            example: /content/dam/my-folder
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/Types'
        - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304_NotModified'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '403':
          $ref: '#/components/responses/403_Forbidden'
        '404':
          $ref: '#/components/responses/404_NotFound'
        '406':
          $ref: '#/components/responses/406_Unacceptable'
    post:
      summary: Creates new folders at the specified paths.
      description: |
        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[]`.
      operationId: createFolders
      security:
        - Bearer: []
          ApiKeyHeader: []
      tags:
        - Folders
      parameters:
        - $ref: '#/components/parameters/Prefer'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              maxItems: 10
              items:
                $ref: '#/components/schemas/CreateFolderRequest'
      responses:
        '200':
          description: 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFoldersCommandResult'
              examples:
                allCreated:
                  summary: All folders created successfully.
                  value:
                    operation: adobe.folders.createFolders
                    status: 200
                    description: Created folders
                    data:
                      values:
                        successes:
                          - type: FOLDER
                            folderId: urn:aaid:aem:cfb1a485-2c79-4276-a0d9-d2f46870ac65
                            path: /content/dam/new-folder
                            name: new-folder
                    errors: []
                    warnings: []
                partialSuccess:
                  summary: Some folders were created; others failed.
                  value:
                    operation: adobe.folders.createFolders
                    status: 200
                    description: Some folders were created; others failed.
                    data:
                      values:
                        successes:
                          - type: FOLDER
                            folderId: urn:aaid:aem:cfb1a485-2c79-4276-a0d9-d2f46870ac65
                            path: /content/dam/new-folder
                            name: new-folder
                        failedFolders:
                          - type: https://api.adobeaemcloud.com/adobe/meta/errors/conflict
                            title: Conflict
                            detail: An entity already exists at /content/dam/existing-folder
                            path: /content/dam/existing-folder
                    errors: []
                    warnings: []
                allFailedConflict:
                  summary: No folders created — all targets already exist (conflict).
                  value:
                    operation: adobe.folders.createFolders
                    status: 200
                    description: No folders were created.
                    data:
                      values:
                        successes: []
                        failedFolders:
                          - type: https://api.adobeaemcloud.com/adobe/meta/errors/conflict
                            title: Conflict
                            detail: An entity already exists at /content/dam/existing-folder
                            path: /content/dam/existing-folder
                    errors: []
                    warnings: []
        '202':
          description: Accepted
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderJobStatus'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '403':
          $ref: '#/components/responses/403_Forbidden'
        '406':
          $ref: '#/components/responses/406_Unacceptable'
  /delete:
    post:
      summary: Delete folder(s) by path
      description: |
        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.
      operationId: deleteFoldersByPath
      security:
        - Bearer: []
          ApiKeyHeader: []
      tags:
        - Folders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteFoldersByPathRequest'
      responses:
        '200':
          description: 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).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFoldersCommandResult'
              examples:
                allFailed:
                  summary: No folders deleted — every target failed.
                  value:
                    operation: adobe.folders.deleteFolders
                    status: 200
                    description: No folders were deleted.
                    data:
                      deletedFolders: []
                      failedFolders:
                        - type: https://api.adobeaemcloud.com/adobe/meta/errors/forbidden
                          title: Forbidden
                          detail: You do not have permission to delete a folder at /content/dam/restricted-folder
                          path: /content/dam/restricted-folder
                    errors: []
                    warnings: []
        '202':
          description: Accepted
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderJobStatus'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '403':
          $ref: '#/components/responses/403_Forbidden'
        '404':
          $ref: '#/components/responses/404_NotFound'
        '406':
          $ref: '#/components/responses/406_Unacceptable'
  /{folderId}:
    parameters:
      - $ref: '#/components/parameters/FolderID'
    head:
      summary: Head request for listing contents under the specified folder ID
      description: 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.
      operationId: headFolderById
      security:
        - Bearer: []
          ApiKeyHeader: []
      tags:
        - Folders
      parameters:
        - $ref: '#/components/parameters/If-None-Match'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/Types'
        - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304_NotModified'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '403':
          $ref: '#/components/responses/403_Forbidden'
        '404':
          $ref: '#/components/responses/404_NotFound'
        '406':
          $ref: '#/components/responses/406_Unacceptable'
    get:
      summary: List contents under the specified folder ID
      description: |
        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.
      operationId: getFolderById
      security:
        - Bearer: []
          ApiKeyHeader: []
      tags:
        - Folders
      parameters:
        - $ref: '#/components/parameters/If-None-Match'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/Types'
        - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: List of children under the specified folder ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderListing'
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '304':
          $ref: '#/components/responses/304_NotModified'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '403':
          $ref: '#/components/responses/403_Forbidden'
        '404':
          $ref: '#/components/responses/404_NotFound'
        '406':
          $ref: '#/components/responses/406_Unacceptable'
    delete:
      summary: Delete folder by its ID
      description: 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.
      operationId: deleteFolder
      security:
        - Bearer: []
          ApiKeyHeader: []
      tags:
        - Folders
      parameters:
        - $ref: '#/components/parameters/Recursive'
        - $ref: '#/components/parameters/Force'
      responses:
        '200':
          description: Folder deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFoldersCommandResult'
        '202':
          description: Accepted
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderJobStatus'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '403':
          $ref: '#/components/responses/403_Forbidden'
        '404':
          $ref: '#/components/responses/404_NotFound'
        '406':
          $ref: '#/components/responses/406_Unacceptable'
  /jobs/{jobId}/status:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      summary: Get the status of an async job
      description: |
        Retrieves the current status of a job created by the folder API.
      operationId: getFolderJobStatus
      security:
        - Bearer: []
          ApiKeyHeader: []
      tags:
        - Folders
      responses:
        '200':
          description: Status of a job being processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderJobStatus'
        '303':
          description: The job has finished executing and results are available at the indicated location.
          headers:
            Location:
              $ref: '#/components/headers/Location'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '403':
          $ref: '#/components/responses/403_Forbidden'
        '404':
          $ref: '#/components/responses/404_NotFound'
        '406':
          $ref: '#/components/responses/406_Unacceptable'
  /jobs/{jobId}/result:
    parameters:
      - $ref: '#/components/parameters/JobId'
    get:
      summary: Get the results of a completed job
      description: |
        Retrieves the current status of a job created by the folder API.
      operationId: getFolderJobResult
      security:
        - Bearer: []
          ApiKeyHeader: []
      tags:
        - Folders
      responses:
        '200':
          description: The results of the completed or failed async job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResult'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '403':
          $ref: '#/components/responses/403_Forbidden'
        '404':
          $ref: '#/components/responses/404_NotFound'
        '406':
          $ref: '#/components/responses/406_Unacceptable'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
  parameters:
    If-None-Match:
      name: If-None-Match
      description: |
        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](https://www.rfc-editor.org/rfc/rfc9110.html#name-if-none-match).
      in: header
      required: false
      schema:
        type: string
    limit:
      in: query
      name: limit
      description: |
        For a paginated request, this parameter defines the maximum number of items to retrieve.
      schema:
        $ref: '#/components/schemas/Limit'
    cursor:
      in: query
      name: cursor
      description: |
        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.
      schema:
        $ref: '#/components/schemas/Cursor'
    Types:
      name: types
      in: query
      required: false
      description: |
        Filter the listing by resource type. Accepts a comma-separated list of type values.
        When omitted, defaults to `FOLDER` only.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/FolderListingItemType'
        default:
          - FOLDER
      style: form
      explode: false
    OrderBy:
      name: orderBy
      in: query
      required: false
      description: |
        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.
      schema:
        $ref: '#/components/schemas/OrderBy'
    Prefer:
      description: |
        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](https://www.rfc-editor.org/rfc/rfc7240.html).
      in: header
      name: Prefer
      required: false
      schema:
        type: string
      examples:
        respond-async:
          value: respond-async
          description: Prefer an asynchronous response.
        respond-async-and-wait:
          value: respond-async, wait=10
          description: Prefer an asynchronous response but wait for up to 10 seconds for the server to process the request synchronously.
    FolderID:
      in: path
      name: folderId
      description: ID of the folder to access
      required: true
      schema:
        type: string
        minLength: 1
      examples:
        sample-folder-id:
          value: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
    Recursive:
      in: query
      name: recursive
      description: If true, delete the directory and all descendants
      required: false
      schema:
        type: boolean
    Force:
      in: query
      name: force
      description: If true, delete the directory even if it is referenced
      required: false
      schema:
        type: boolean
    JobId:
      in: path
      name: jobId
      description: ID of a backend asynchronous job
      required: true
      schema:
        type: string
        format: uuid
      examples:
        sample-job-id:
          value: 542c88b4-e136-4341-9221-ae42d3d70b10
  schemas:
    Limit:
      description: |
        For a paginated request, this parameter defines the maximum number of items to retrieve.
      type: integer
      format: int32
      minimum: 1
      maximum: 50
    Cursor:
      description: |
        A cursor is an opaque string that can be used in API calls which support paginating the response. A non-existent cursor
        signifies that the returned list does not have more elements.
      type: string
      minLength: 1
    FolderListingItemType:
      description: |
        The type of resource in a folder listing response.
        Used as the filter value in the `types` query parameter.
      type: string
      enum:
        - FOLDER
        - ASSET
    OrderBy:
      description: |
        The value of an `orderBy` parameter contains a comma-separated list of expressions used to sort the items.

        The expression may include the suffix `asc` for ascending or `desc` for descending, separated from the property
        name by one or more spaces. If `asc` or `desc` is not specified, the service will order by the specified
        property in ascending order.

        Items will be sorted by the result values of the first expression; items with the same value for the first
        expression are sorted by the result value of the second expression and so on. The sort order is the
        inherent order for the type of the property.
      type: string
      minLength: 1
      example: metadata.repositoryMetadata.repo:size desc,metadata.repositoryMetadata.repo:createDate asc
    Folder:
      description: A reference to a folder. Only high-level properties are included.
      allOf:
        - $ref: '#/components/schemas/FolderListingItem'
        - type: object
          properties:
            type:
              description: |
                The type of this listing item. Always `FOLDER` for folder entries.
              allOf:
                - $ref: '#/components/schemas/FolderListingItemType'
              default: FOLDER
              readOnly: true
            name:
              type: string
              minLength: 1
              description: The name of the folder, usually the last node of the path.
              example: test-folder
            title:
              type: string
              nullable: true
              description: |
                The title of the folder for display purposes.
              example: Test Folder
            folderId:
              type: string
              minLength: 1
              description: The unique identifier for the folder
              readOnly: true
            path:
              type: string
              minLength: 1
              description: The path to the folder
              example: /content/dam/test-folder
              readOnly: true
          required:
            - type
            - folderId
            - name
            - path
    FolderListingItem:
      description: |
        A single item in a folder listing response. Can be either a folder or an asset,
        discriminated by the `type` property.
      type: object
      properties:
        type:
          $ref: '#/components/schemas/FolderListingItemType'
      required:
        - type
      discriminator:
        propertyName: type
        mapping:
          FOLDER: '#/components/schemas/Folder'
          ASSET: '#/components/schemas/Asset'
    Asset:
      description: |
        A reference to an asset. Only high-level properties are included.
      allOf:
        - $ref: '#/components/schemas/FolderListingItem'
        - type: object
          properties:
            type:
              description: The type of this listing item. Always `ASSET` for asset entries.
              allOf:
                - $ref: '#/components/schemas/FolderListingItemType'
              default: ASSET
              readOnly: true
            assetId:
              type: string
              minLength: 1
              description: The unique identifier for the asset
              readOnly: true
            name:
              type: string
              minLength: 1
              description: The name of the asset, including the file extension
              example: my-image.png
            size:
              type: integer
              format: int64
              description: The size of the asset in bytes
              readOnly: true
              example: 1048576
            lastModifiedAt:
              type: string
              format: date-time
              description: The date and time the asset was last modified
              readOnly: true
              example: '2026-03-15T10:30:00Z'
          required:
            - type
            - assetId
            - name
    FolderListing:
      type: object
      properties:
        cursor:
          $ref: '#/components/schemas/Cursor'
        self:
          $ref: '#/components/schemas/Folder'
        children:
          description: The items contained in this folder, filtered and sorted according to the query parameters
          type: array
          items:
            $ref: '#/components/schemas/FolderListingItem'
      example:
        self:
          type: FOLDER
          folderId: urn:aaid:aem:1a034bee-ebda-4787-bad3-f924d0772b75
          name: my-folder
          title: My Folder
          path: /content/dam/my-folder
        children:
          - type: FOLDER
            folderId: urn:aaid:aem:cfb1a485-2c79-4276-a0d9-d2f46870ac65
            name: child-folder-1
            title: Child Folder 1
            path: /content/dam/my-folder/child-folder-1
          - type: ASSET
            assetId: urn:aaid:aem:7c4f2b3a-1234-5678-9abc-def012345678
            name: hero-image.png
            size: 1048576
            lastModifiedAt: '2026-03-15T10:30:00Z'
          - type: FOLDER
            folderId: urn:aaid:aem:d92372b8-5187-11ee-be56-0242ac120002
            name: child-folder-2
            title: Child Folder 2
            path: /content/dam/my-folder/child-folder-2
    ProblemDetails:
      description: A [RFC7807](https://www.rfc-editor.org/rfc/rfc7807) JSON Problem Details Object
      type: object
      properties:
        type:
          type: string
          description: A URI reference [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) to a URL, which, when dereferenced, provides human readable documentation for the problem type.  The problem type may be equivalent to the `status` or may be a "sub-type".  This URI is not intended to be parsed by clients; rather it should be treated as an opaque string that uniquely represents the error condition as-is.
          minLength: 1
        title:
          type: string
          description: A short, human-readable summary of the problem type.
          minLength: 1
        status:
          type: integer
          description: The HTTP status code ([RFC9110], Section 15) generated by the origin server for this occurrence of the problem.
          minLength: 1
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
          minLength: 1
        requestId:
          type: string
          description: |
            A unique identifier that is assigned to the request, either by the API caller or by the service itself.
          minLength: 1
      required:
        - type
        - title
        - status
        - detail
    CreateFolderRequest:
      type: object
      properties:
        path:
          description: The path of the folder to be created
          type: string
          example: /content/dam/my-folder
          minLength: 1
        title:
          description: The title of the folder to be created
          type: string
          example: My Folder
      required:
        - path
    CommandResultMessage:
      description: CommandResultMessage Object to encapsulate the result of a command.
      type: object
      properties:
        type:
          type: string
          description: A URI reference [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) that identifies the message type.
          minLength: 1
        title:
          type: string
          description: A short, human-readable summary of the problem type.
          minLength: 1
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        context:
          type: object
          description: |
            An optional object containing additional context information about the problem.

            Each command MUST provide its own schema definition for this object, by defining all the properties a client is
            expected to encounter.
      required:
        - type
        - title
    FailedFolderItem:
      description: |
        A folder that failed to be processed during a folders command. Combines the problem
        details of the failure with the identity of the folder to which it applies.

        At least one of `path` or `id` identifies the folder. Path-addressed operations
        (`createFolders`, `deleteFoldersByPath`, `moveFolders`/`copyFolders` by path) populate
        `path`, and `id` is included when known. Id-addressed operations (`moveFolders`/
        `copyFolders` by id) populate `id`; `path` is included once the id resolves to a folder.
      allOf:
        - type: object
          properties:
            path:
              type: string
              minLength: 1
              description: The path of the folder to which this failure applies, when known.
            id:
              type: string
              minLength: 1
              description: The unique identifier of the folder to which this failure applies, when known.
          anyOf:
            - required:
                - path
            - required:
                - id
        - $ref: '#/components/schemas/CommandResultMessage'
    FailedFolders:
      type: array
      description: An optional array of folders that failed to be processed during the operation.
      maxItems: 10
      items:
        $ref: '#/components/schemas/FailedFolderItem'
    CreateFoldersCommandResultData:
      type: object
      properties:
        values:
          type: object
          properties:
            successes:
              type: array
              maxItems: 10
              items:
                $ref: '#/components/schemas/Folder'
            failedFolders:
              $ref: '#/components/schemas/FailedFolders'
    CommandResult:
      description: |
        The result of a command. A command is an operation that changes a system in a different way than via a CRUD
        request to a resource.
      type: object
      properties:
        operation:
          type: string
          description: The operation that was performed.
          minLength: 1
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code ([RFC9110, Section 15](https://www.rfc-editor.org/rfc/rfc9110.html#section-15))
            generated by the origin server corresponding to this operation.
        description:
          type: string
          description: A human-readable explanation specific to this command, explaining the status.
          minLength: 1
        data:
          type: object
          description: |
            The data returned by the operation, which will vary by the implementing command. Each command
            MUST provide its own schema definition for this object, by defining all the properties a client is
            expected to encounter.
        errors:
          type: array
          description: An optional array of errors that occurred during the operation.
          items:
            $ref: '#/components/schemas/CommandResultMessage'
        warnings:
          type: array
          description: An optional array of warnings that occurred during the operation.
          items:
            $ref: '#/components/schemas/CommandResultMessage'
      required:
        - operation
        - status
        - description
    CreateFoldersCommandResult:
      description: |
        The result of an `adobe.folders.createFolders` command.
      allOf:
        - type: object
          properties:
            operation:
              type: string
              default: adobe.folders.createFolders
            data:
              $ref: '#/components/schemas/CreateFoldersCommandResultData'
        - $ref: '#/components/schemas/CommandResult'
      required:
        - operation
      example:
        operation: adobe.folders.createFolders
        status: 200
        description: Some folders have been created; others failed.
        data:
          values:
            successes:
              - type: FOLDER
                folderId: urn:aaid:aem:cfb1a485-2c79-4276-a0d9-d2f46870ac65
                path: /content/dam/new-folder
                name: new-folder
            failedFolders:
              - type: https://api.adobeaemcloud.com/adobe/meta/errors/conflict
                title: Conflict
                detail: A folder already exists at /content/dam/existing-folder
                path: /content/dam/existing-folder
              - type: https://api.adobeaemcloud.com/adobe/meta/errors/forbidden
                title: Forbidden
                detail: You do not have permission to create a folder at /content/dam/restricted-folder
                path: /content/dam/restricted-folder
    FolderJobStatus:
      type: object
      description: The status of a folder async job.
      properties:
        jobId:
          type: string
          format: uuid
          minLength: 36
        state:
          type: string
          enum:
            - PROCESSING
            - COMPLETED
            - COMPLETED_WITH_ERRORS
            - FAILED
          description: The state of the async job. Possible values are `PROCESSING`, `COMPLETED`, `COMPLETED_WITH_ERRORS`, or `FAILED`. A state of `COMPLETED_WITH_ERRORS` indicates that at least one of the operations contained in the async job contains errors or warnings.  To inspect the errors or warnings, request the job result by following the link provided in the Location header.
          minLength: 6
        status:
          type: string
          description: Additional information about processing state. If an error occurred, error information will appear here.
      required:
        - jobId
        - state
      example:
        jobId: 85f7c90a-a252-4e82-8cf3-3c989829cdf9
        state: PROCESSING
    DeleteFoldersByPathRequest:
      type: object
      properties:
        paths:
          description: The paths of the folders to be deleted.
          type: array
          uniqueItems: true
          maxItems: 10
          items:
            type: string
            description: Folder path to be deleted
            example: /content/dam/my-folder
        recursive:
          description: If true, delete the directory and all descendants
          type: boolean
        force:
          description: If true, delete the directory even if it is referenced
          type: boolean
      required:
        - paths
    DeleteFoldersCommandResult:
      description: |
        The result of an `adobe.folders.deleteFolders` command.
      allOf:
        - type: object
          properties:
            operation:
              type: string
              default: adobe.folders.deleteFolders
            data:
              type: object
              description: Delete Folders Command Result
              properties:
                deletedFolders:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                    minLength: 1
                failedFolders:
                  $ref: '#/components/schemas/FailedFolders'
        - $ref: '#/components/schemas/CommandResult'
      required:
        - operation
      example:
        operation: adobe.folders.deleteFolders
        status: 200
        description: Some folders have been deleted; others failed.
        data:
          deletedFolders:
            - /content/dam/test-folder
            - /content/dam/another-folder
          failedFolders:
            - type: https://api.adobeaemcloud.com/adobe/meta/errors/forbidden
              title: Forbidden
              detail: You do not have permission to delete a folder at /content/dam/restricted-folder
              path: /content/dam/restricted-folder
            - type: https://api.adobeaemcloud.com/adobe/meta/errors/not_implemented
              title: Not Implemented
              detail: Support for the operation on /unsupported/folder hasn't been implemented.
              path: /unsupported/folder
    MovedFolderResultItem:
      type: object
      description: The result of a single folder move operation.
      additionalProperties: false
      properties:
        id:
          type: string
          description: The ID of the moved folder. This is the same ID as before the move — the folder entity does not change, only its location.
        path:
          type: string
          description: The final absolute path after the move.
        sourcePath:
          type: string
          description: The absolute path of the folder before the move.
        previousParentId:
          type: string
          description: The ID of the parent folder before the move.
        previousParentPath:
          type: string
          description: The absolute path of the parent folder before the move.
        destinationParentId:
          type: string
          description: The ID of the parent folder the folder was moved into.
        destinationParentPath:
          type: string
          description: The absolute path of the parent folder the folder was moved into.
      required:
        - id
        - path
        - sourcePath
        - previousParentId
        - previousParentPath
        - destinationParentId
        - destinationParentPath
    MoveFoldersCommandResult:
      description: |
        The result of an `adobe.folders.moveFolders` command.
      allOf:
        - type: object
          properties:
            operation:
              type: string
              default: adobe.folders.moveFolders
            data:
              type: object
              description: Move Folders Command Result
              properties:
                movedFolders:
                  type: array
                  description: Per-item results for the move operation.
                  maxItems: 10
                  items:
                    $ref: '#/components/schemas/MovedFolderResultItem'
                failedFolders:
                  $ref: '#/components/schemas/FailedFolders'
              required:
                - movedFolders
        - $ref: '#/components/schemas/CommandResult'
      required:
        - operation
      example:
        operation: adobe.folders.moveFolders
        status: 200
        description: Some folders have been moved; others failed.
        data:
          movedFolders:
            - id: urn:aaid:aem:cfb1a485-2c79-4276-a0d9-d2f46870ac65
              path: /content/dam/archive/2024/projects
              sourcePath: /content/dam/2024/projects
              previousParentId: urn:aaid:aem:a1b2c3d4-5678-90ab-cdef-1234567890ab
              previousParentPath: /content/dam/2024
              destinationParentId: urn:aaid:aem:8f3e9a7b-1234-5678-9abc-def012345678
              destinationParentPath: /content/dam/archive/2024
          failedFolders:
            - type: https://api.adobeaemcloud.com/adobe/meta/errors/forbidden
              title: Forbidden
              detail: You do not have permission to move a folder at /content/dam/2024/assets
              path: /content/dam/2024/assets
            - type: https://api.adobeaemcloud.com/adobe/meta/errors/not_found
              title: Not Found
              detail: The source folder to move could not be found.
              id: urn:aaid:aem:d92372b8-5187-11ee-be56-0242ac120002
    CopiedFolderResultItem:
      type: object
      description: The result of a single folder copy operation.
      additionalProperties: false
      properties:
        sourceId:
          type: string
          description: The ID of the original source folder. Returned regardless of whether the request used BY_ID or BY_PATH addressing.
        sourcePath:
          type: string
          description: The absolute path of the source folder at the time of the operation.
        id:
          type: string
          description: The ID of the newly created copy. This is a different ID from sourceId.
        path:
          type: string
          description: The absolute path of the newly created copy.
        destinationParentId:
          type: string
          description: The ID of the parent folder the copy was placed under.
        destinationParentPath:
          type: string
          description: The absolute path of the parent folder the copy was placed under.
      required:
        - sourceId
        - sourcePath
        - id
        - path
        - destinationParentId
        - destinationParentPath
    CopyFoldersCommandResult:
      description: |
        The result of an `adobe.folders.copyFolders` command.
      allOf:
        - type: object
          properties:
            operation:
              type: string
              default: adobe.folders.copyFolders
            data:
              type: object
              description: Copy Folders Command Result
              properties:
                copiedFolders:
                  type: array
                  description: Per-item results for the copy operation. Each entry corresponds to one successfully copied folder.
                  maxItems: 10
                  items:
                    $ref: '#/components/schemas/CopiedFolderResultItem'
                failedFolders:
                  $ref: '#/components/schemas/FailedFolders'
              required:
                - copiedFolders
        - $ref: '#/components/schemas/CommandResult'
      required:
        - operation
      example:
        operation: adobe.folders.copyFolders
        status: 200
        description: Some folders have been copied; others failed.
        data:
          copiedFolders:
            - sourceId: <source-folder-id-1>
              sourcePath: /content/dam/2024/projects
              id: <copied-folder-id-1>
              path: /content/dam/archive/2024/projects
              destinationParentId: <destination-parent-id>
              destinationParentPath: /content/dam/archive/2024
            - sourceId: <source-folder-id-2>
              sourcePath: /content/dam/2024/assets
              id: <copied-folder-id-2>
              path: /content/dam/archive/2024/assets
              destinationParentId: <destination-parent-id>
              destinationParentPath: /content/dam/archive/2024
          failedFolders:
            - type: https://api.adobeaemcloud.com/adobe/meta/errors/forbidden
              title: Forbidden
              detail: You do not have permission to copy a folder at /content/dam/2024/restricted-folder
              path: /content/dam/2024/restricted-folder
    JobResult:
      description: The result of a completed job.
      discriminator:
        propertyName: operation
        mapping:
          adobe.folders.createFolders: '#/components/schemas/CreateFoldersCommandResult'
          adobe.folders.deleteFolders: '#/components/schemas/DeleteFoldersCommandResult'
          adobe.folders.moveFolders: '#/components/schemas/MoveFoldersCommandResult'
          adobe.folders.copyFolders: '#/components/schemas/CopyFoldersCommandResult'
      anyOf:
        - $ref: '#/components/schemas/CreateFoldersCommandResult'
        - $ref: '#/components/schemas/DeleteFoldersCommandResult'
        - $ref: '#/components/schemas/MoveFoldersCommandResult'
        - $ref: '#/components/schemas/CopyFoldersCommandResult'
  headers:
    ETag:
      schema:
        type: string
      description: |
        The `ETag` field in a response provides the current entity tag for the selected representation, as determined at the
        conclusion of handling the request. An entity tag is an opaque validator for differentiating between multiple
        representations of the same resource, regardless of whether those multiple representations are due to resource state
        changes over time, content negotiation resulting in multiple representations being valid at the same time, or both.
        An entity tag consists of an opaque quoted string, possibly prefixed by a weakness indicator.

        For more details, please head over to [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-etag).
      required: true
    Last-Modified:
      schema:
        type: string
      description: |
        The "Last-Modified" header field in a response provides a timestamp indicating the date and time at which the origin
        server believes the selected representation was last modified, as determined at the conclusion of handling the
        request.

        For more details, please head over to [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-last-modified).
      required: true
    Location:
      schema:
        type: string
        format: uri
      description: |
        The `Location` header field is used in some responses to refer to a specific resource in relation to the response.
        The type of relationship is defined by the combination of request method and status code semantics.

        For more details, please head over to [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-location).
      required: true
  responses:
    304_NotModified:
      description: Not Modified
      content: {}
      headers:
        ETag:
          $ref: '#/components/headers/ETag'
        Last-Modified:
          $ref: '#/components/headers/Last-Modified'
    400_BadRequest:
      description: |
        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.
      content:
        application/problem+json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ProblemDetails'
              - type: object
                properties:
                  status:
                    type: integer
                    default: 400
                  title:
                    type: string
                    default: Bad Request
          example:
            type: http://api.adobeaemcloud.com/adobe/meta/errors/bad_request
            title: Bad Request
            status: 400
            detail: Bad request, please check that you have provided the correct parameters and that they are valid.
    401_Unauthorized:
      description: |
        Unauthorized. Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.
      content:
        application/problem+json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ProblemDetails'
              - type: object
                properties:
                  status:
                    type: integer
                    default: 401
                  title:
                    type: string
                    default: Unauthorized
          example:
            type: http://api.adobeaemcloud.com/adobe/meta/errors/unauthorized
            title: Unauthorized
            status: 401
            detail: The request did not contain a valid Authorization header.
    403_Forbidden:
      description: |
        Forbidden. Indicates that the server understood the request but refuses to fulfil it.
      content:
        application/problem+json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ProblemDetails'
              - type: object
                properties:
                  status:
                    type: integer
                    default: 403
                  title:
                    type: string
                    default: Forbidden
          example:
            type: http://api.adobeaemcloud.com/adobe/meta/errors/forbidden
            title: Forbidden
            status: 403
            detail: The credentials provided do not have sufficient permissions to access this resource.
    404_NotFound:
      description: |
        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.
      content:
        application/problem+json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ProblemDetails'
              - type: object
                properties:
                  status:
                    type: integer
                    default: 404
                  title:
                    type: string
                    default: Not Found
          example:
            type: http://api.adobeaemcloud.com/adobe/meta/errors/not_found
            title: Not Found
            status: 404
            detail: The requested resource could not be found.
    406_Unacceptable:
      description: |
        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.
      content:
        application/problem+json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ProblemDetails'
              - type: object
                properties:
                  title:
                    type: string
                    example: Unacceptable
                  status:
                    type: integer
                    default: 406
          example:
            type: http://api.adobeaemcloud.com/adobe/meta/errors/not_acceptable
            title: Not Acceptable
            status: 406
            detail: |
              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.