Adobe Suite Tag categories API

openapi: 3.2.0
info:
  title: Unified Tags Tag categories 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: Tag categories
  description: Tag categories let you organize your tags into meaningful sets, allowing you to provide more context to the tag's purpose.
paths:
  /unifiedtags/tagCategory:
    get:
      tags:
      - Tag categories
      summary: List tag categories
      operationId: listTagCategories
      parameters:
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/limitTagCategories'
      - $ref: '#/components/parameters/propertyTagCategories'
      - $ref: '#/components/parameters/sortByTagCategories'
      - $ref: '#/components/parameters/sortOrderTagCategories'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      responses:
        200:
          x-summary: Success
          description: A list of tag categories that belongs to the organization is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tagCategoriesList'
    post:
      tags:
      - Tag categories
      summary: Create a new tag category
      operationId: createTagCategory
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      requestBody:
        description: The request body to create the tag category.
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/createTagCategoryBody'
        required: true
      responses:
        200:
          x-summary: Success
          description: The tag category was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tagCategory'
  /unifiedtags/tagCategory/{TAG_CATEGORY_ID}:
    get:
      tags:
      - Tag categories
      summary: Retrieve a specific tag category
      operationId: retrieveTagCategory
      parameters:
      - $ref: '#/components/parameters/tag-category-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      responses:
        200:
          x-summary: Success
          description: The specified tag category was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tagCategory'
    patch:
      tags:
      - Tag categories
      summary: Update a specific tag category
      description: '**Important:** Only the system administrator and the product administrator can use this API call.'
      operationId: updateTagCategory
      parameters:
      - $ref: '#/components/parameters/tag-category-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      requestBody:
        description: The request body to update the tag category.
        content:
          '*/*':
            schema:
              type: array
              items:
                $ref: '#/components/schemas/updateTagCategoryBody'
      responses:
        200:
          x-summary: Success
          description: The tag category was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/updatedTagCategory'
    delete:
      tags:
      - Tag categories
      summary: Delete a specific tag category
      description: '**Important:** Only the system administrator and the product administrator can use this API call.'
      operationId: deleteTagCategory
      parameters:
      - $ref: '#/components/parameters/tag-category-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-api-key'
      responses:
        200:
          x-summary: Success
          description: The tag category was successfully deleted.
          content: {}
components:
  parameters:
    tag-category-id:
      name: TAG_CATEGORY_ID
      in: path
      description: The ID of the tag category.
      required: true
      schema:
        type: string
    limitTagCategories:
      name: limit
      in: query
      description: The maximum number of tag categories you want retrieved per page.
      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
    start:
      name: start
      in: query
      description: The location where the list of results starts from. You can use this to indicate the starting index for pagination of results.
      schema:
        type: string
    sortOrderTagCategories:
      name: sortOrder
      in: query
      description: The direction in which the tag categories are sorted by. Supported values include `asc` and `desc`.
      schema:
        type: string
    propertyTagCategories:
      name: property
      in: query
      description: The attribute you want to filter by when retrieving tag categories.
      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
    sortByTagCategories:
      name: sortBy
      in: query
      description: The order in which the tag categories are sorted by. Supported values include `name`, `createdAt`, and `modifiedAt`.
      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
  schemas:
    updateTagCategoryBody:
      type: object
      properties:
        op:
          description: The operation for the PATCH call. Only `replace` is supported.
          type: string
          example: replace
        path:
          description: The path of the field you want to update. Supported values include `/name` and `/description`.
          type: string
          example: description
        value:
          type: string
          description: The updated value of the field you want to update.
          example: Updated sample description
        from:
          type: string
          description: The original value of the field you want to update.
          example: Sample test category description
    updatedTagCategory:
      type: object
      allOf:
      - $ref: '#/components/schemas/tagCategory'
      - type: object
        properties:
          description:
            type: string
            description: The updated value of the description.
            example: Updated sample description
    tagCategory:
      type: object
      properties:
        id:
          type: string
          description: The ID of the tag category.
          example: e2b7c656-067b-4413-a366-adde0401df50
        name:
          type: string
          description: The name of the tag category.
          example: Sample Tag Category
        description:
          type: string
          description: A description for the tag category.
          example: Sample tag category description
        org:
          type: string
          description: The ID of the organization that the tag category belongs to.
          example: '{ORG_ID}'
        createdBy:
          description: The ID of the user who created the tag category.
          type: string
          example: '{USER_ID}'
        createdAt:
          description: The timestamp that the tag category was created at.
          type: string
          example: '1661752268000'
        modifiedBy:
          description: The ID of the user who last modified the tag category.
          type: string
          example: '{USER_ID}'
        modifiedAt:
          description: The timestamp that the tag category was created at.
          type: string
          example: '1661752268000'
        tagCount:
          description: The number of tags that belong to the tag category.
          type: integer
          example: 0
    createTagCategoryBody:
      type: object
      properties:
        name:
          description: The name for the tag category you want to create.
          type: string
          example: Sample Test Category
        description:
          description: The description of the tag category you want to create.
          type: string
          example: Sample test category description
    tagCategoriesList:
      type: object
      properties:
        _page:
          type: object
          properties:
            count:
              description: The number of tag categories that match the given query parameters listed.
              type: integer
              example: 1
            limit:
              description: The number of tag categories returned per page.
              type: integer
              example: 10
            property:
              description: The property used to filter the tag categories.
              type: array
              example: []
              items: {}
        tags:
          type: array
          description: The list of tag categories that match the property filter.
          items:
            $ref: '#/components/schemas/tagCategory'