openapi: 3.2.0
info:
  title: Unified Tags Folders API
  version: '1.0'
  description: "Use the Unified Tags API to create folders, tags, and tag categories, which let you better organize your business objects. \n\n- **Related documentation**:\n  - [Unified Tags documentation](https://experienceleague.adobe.com/en/docs/experience-platform/administrative-tags/api/overview)\n\n- **Visualize API calls with Postman (a free, third-party software)**:\n  - [Real-time Customer Profile API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Real-time%20Customer%20Profile%20API.postman_collection.json)\n  - [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n  - [Steps for importing environments and collections in Postman](https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n- **API paths**:\n  - Gateway URL: https://<span>experience.adobe.io/\n\n- **Required headers**:\n  - All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).\n  - All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type`. Accepted values specific to each call are provided in the call parameters.     \n\n- **API error handling**:\n  - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors)."
servers:
- url: https://experience.adobe.io
tags:
- name: Folders
  description: Folders are a capability that let you better organize your business objects for easier navigability and categorization.
paths:
  /unifiedfolders/folders/{FOLDER_TYPE}:
    post:
      tags:
      - Folders
      summary: Create a folder
      operationId: createFolder
      parameters:
      - $ref: '#/components/parameters/folder-type'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-sandbox-name'
      requestBody:
        description: The request body to create the folder.
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/createFolderBody'
        required: true
      responses:
        200:
          x-summary: Created
          description: A new folder was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folder'
  /unifiedfolders/folders/{FOLDER_TYPE}/{FOLDER_ID}:
    get:
      tags:
      - Folders
      summary: Retrieve a specified folder
      operationId: retrieveFolder
      parameters:
      - $ref: '#/components/parameters/folder-type'
      - $ref: '#/components/parameters/folder-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-sandbox-name'
      responses:
        200:
          x-summary: Success
          description: Returns the specified folder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folder'
    patch:
      tags:
      - Folders
      summary: Update a specific folder
      operationId: updateFolder
      parameters:
      - $ref: '#/components/parameters/folder-type'
      - $ref: '#/components/parameters/folder-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-sandbox-name'
      requestBody:
        description: The request body to update the folder.
        content:
          '*/*':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/updateFolderBody'
        required: true
      responses:
        200:
          x-summary: Success
          description: The folder was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updatedFolder'
    delete:
      tags:
      - Folders
      summary: Delete a specific folder
      operationId: deleteFolder
      parameters:
      - $ref: '#/components/parameters/folder-type'
      - $ref: '#/components/parameters/folder-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-sandbox-name'
      responses:
        200:
          x-summary: Success
          description: The folder was successfully deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deleteFolderResponse'
  /unifiedfolders/folders/{FOLDER_TYPE}/{FOLDER_ID}/subfolders:
    get:
      tags:
      - Folders
      summary: Retrieve a folder's subfolders
      operationId: getSubfolders
      parameters:
      - $ref: '#/components/parameters/folder-type'
      - $ref: '#/components/parameters/folder-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-sandbox-name'
      responses:
        200:
          x-summary: Success
          description: The list of subfolders was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/foldersList'
  /unifiedfolders/folders/{FOLDER_TYPE}/{FOLDER_ID}/validate:
    get:
      tags:
      - Folders
      summary: Validate a specific folder
      description: Use this endpoint to validate if a folder is eligible to have objects in it.
      operationId: validateFolder
      parameters:
      - $ref: '#/components/parameters/folder-type'
      - $ref: '#/components/parameters/folder-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-sandbox-name'
      responses:
        200:
          x-summary: Success
          description: The folder was successfully validated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/folder'
components:
  schemas:
    foldersList:
      type: object
      description: A list of subfolders for the requested folder.
      properties:
        id:
          type: string
          example: c626b4f7-223b-4486-8900-00c266e31dd1
          description: The ID of the folder.
        name:
          type: string
          example: ParentFolder
          description: The name of the folder.
        noun:
          type: string
          example: dataset
          description: The type of the business object that the folder contains.
        imsOrg:
          type: string
          example: '{IMS_ORG}'
          description: The ID of the organization that the folder belongs to.
        sandboxId:
          type: string
          example: '{SANDBOX_ID}'
          description: The ID of the sandbox that the folder belongs to.
        sandboxName:
          type: string
          example: prod
          description: The name of the sandbox that the folder belongs to.
        createdBy:
          type: string
          example: 'null'
          description: The ID of the user who created the folder.
        createdAt:
          type: string
          example: '2023-01-12T03:31:00.118+00:00'
          description: The date and time that the folder was created.
        modifiedBy:
          type: string
          example: 'null'
          description: The ID of the user who last modified the folder.
        modifiedAt:
          type: string
          example: '2023-01-13T05:47:06.718+00:00'
          description: The date and time that the folder was last modified.
        _links:
          type: object
          example: null
          description: A link to the folder.
        children:
          type: array
          description: The child folders for the parent folders.
          items:
            $ref: '#/components/schemas/childFolder'
    updatedFolder:
      type: object
      allOf:
      - $ref: '#/components/schemas/folder'
      - type: object
        properties:
          name:
            type: string
            description: The updated name for the folder.
            example: RenamedSampleFolder
    folder:
      type: object
      properties:
        id:
          type: string
          example: 83f8287c-767b-4106-b271-257282fd170e
          description: The ID of the folder.
        name:
          type: string
          example: SampleFolder
          description: The name of the folder.
        noun:
          type: string
          example: dataset
          description: The type of business objects that belong to the folder. Possible values include `dataset` and `segment`.
        imsOrg:
          type: string
          example: '{ORG_ID}'
          description: The ID of the organization that the folder belongs to.
        sandboxId:
          type: string
          example: '{SANDBOX_ID}'
          description: The ID of the sandbox that the folder belongs to.
        sandboxName:
          type: string
          example: prod
          description: The name of the sandbox that the folder belongs to.
        createdBy:
          type: string
          example: '{USER_ID}'
          description: The ID of the user who created the folder.
        createdAt:
          type: string
          example: '2023-10-01T08:47:06.192+00:00'
          description: The date and time that the folder was created.
        modifiedBy:
          type: string
          example: '{USER_ID}'
          description: The ID of the user who last modified the folder.
        modifiedAt:
          type: string
          example: '2023-10-01T08:47:06.192+00:00'
          description: The date and time that the folder was last modified.
        status:
          type: string
          example: IN_USE
          description: The status of the folder. Possible values include `IN_USE` and `ARCHIVED`.
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  example: /folders/dataset/83f8287c-767b-4106-b271-257282fd170e
          description: A link to the folder.
    updateFolderBody:
      type: object
      description: The request body to update the folder.
      required:
      - op
      - path
      - value
      properties:
        op:
          type: string
          description: The type of operation for the PATCH operation. Only `replace` is supported.
          example: replace
          enum:
          - replace
        path:
          type: string
          example: /name
          description: The path for the field that needs to be updated.
        value:
          type: string
          description: The updated value for the field that needs to be updated.
          example: RenamedSampleFolder
    createFolderBody:
      type: object
      properties:
        name:
          type: string
          description: The name of the folder you want to create.
          example: SampleFolder
        parentId:
          type: string
          description: The parent ID of the folder you want to create.
          example: 6a5e0927-1527-4abc-9993-376fd7067ca5
    deleteFolderResponse:
      type: object
      description: A successful deletion response body.
      properties:
        message:
          type: string
          example: delete request accepted successfully
    childFolder:
      type: object
      allOf:
      - $ref: '#/components/schemas/folder'
      - type: object
        properties:
          name:
            type: string
            example: ChildFolder
            description: The name for the child folder.
          parentId:
            type: string
            example: c626b4f7-223b-4486-8900-00c266e31dd1
            description: The ID of the parent folder.
          children:
            type: array
            description: An array showing children folders that belong to the child folder.
            example: []
            items: {}
          _links:
            type: object
            example: null
            description: A link to the child folder.
  parameters:
    folder-type:
      name: FOLDER_TYPE
      in: path
      description: The type of folder you're retrieving. Supported values include `segment` and `dataset`.
      required: true
      schema:
        type: string
    authorization:
      name: Authorization
      in: header
      description: The access token which can be copied from your Experience Platform integration, prefixed with "Bearer ". For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    content-type:
      name: Content-Type
      in: header
      description: The type of content being sent in the body of the request. This value should be `application/json`.
      required: true
      schema:
        type: string
    x-api-key:
      name: x-api-key
      in: header
      description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-gw-ims-org-id:
      name: x-gw-ims-org-id
      in: header
      description: The Organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-sandbox-name:
      name: x-sandbox-name
      in: header
      description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place. See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.
      required: true
      schema:
        type: string
    folder-id:
      name: FOLDER_ID
      in: path
      description: The ID of the folder.
      required: true
      schema:
        type: string