Adobe Suite Labels API

openapi: 3.2.0
info:
  title: Policy Service Labels API
  description: "Adobe Experience Platform Data Governance simplifies and streamlines the process of categorizing data and creating data usage policies. Once data labels have been applied and data usage policies are in place, marketing actions can be evaluated to ensure the correct use of data.\n\nUse the Policy Service API to programmatically manage data usage labels, policies, and marketing actions. The API also provides endpoints to evaluate marketing actions against specific data usage labels to test for policy violations.\n\nNote: You can use the [Dataset Service API](./dataset-service.yaml) to manage data usage labels for an existing dataset.\n- **Related documentation**:\n  - [Data Governance documentation](http://www.adobe.com/go/data-governance-overview-en)\n\n- **Visualize API calls with Postman (a free, third-party software)**:\n  - [Policy Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Policy%20Service%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  - PLATFORM Gateway URL: https://<span>platform.adobe.io/\n  - Base path for this API: /data/foundation/dulepolicy\n  - Example of a complete path: https://<span>platform.adobe.io/data/foundation/dulepolicy/labels/custom\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 resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n  - All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`.\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)."
  version: '1.0'
servers:
- url: //{environment}.adobe.io/data/foundation/dulepolicy
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Labels
  description: Data usage labels allow you to categorize datasets and fields according to usage policies that apply to that data.
paths:
  /labels/core:
    get:
      tags:
      - Labels
      summary: List core labels
      description: '>**NOTE**: For more information on using this operation, see the [labels endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/labels.html) on Experience League.'
      operationId: listCoreLabels
      parameters:
      - 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
      - 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
      - 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
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      - name: property
        in: query
        description: 'Filters responses based on whether a specific property exists, or whose value passes a conditional expression (e.g. `?property=name==C1`). Only the `name` property is supported for core resources. For custom resources, additional supported property values include `status`, `created`, `createdClient`, `createdUser`, `updated`, `updatedClient`, and `updatedUser`. '
        schema:
          type: string
      - name: orderby
        in: query
        description: A comma-separated list of properties by which the returned list of resources will be sorted.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: start
        in: query
        description: 'Indicates the pagination value for the returned list. This value should be obtained from a previous call''s `_page.next` property. Should be omitted for a first page of results. '
        schema:
          type: string
      - name: limit
        in: query
        description: A positive integer, indicating the number of results to limit the response to.
        schema:
          type: integer
      responses:
        '200':
          description: A successful response returns a list of core labels.
          x-summary: Core labels retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsPage'
  /labels/core/{LABEL_NAME}:
    get:
      tags:
      - Labels
      summary: Retrieve a core label
      description: '>**NOTE**: For more information on using this operation, see the [labels endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/labels.html) on Experience League.'
      operationId: retrieveCoreLabel
      parameters:
      - name: LABEL_NAME
        in: path
        description: The name of the core label.
        required: true
        schema:
          type: string
      - 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
      - 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
      - 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
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response returns the details of the retrieved core label.
          x-summary: Core label retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelsResponse'
        '404':
          description: No core label was found for the given name.
          x-summary: Core label not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoreNotFoundError'
  /labels/custom:
    get:
      tags:
      - Labels
      summary: List custom labels
      description: '>**NOTE**: For more information on using this operation, see the [labels endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/labels.html) on Experience League.'
      operationId: listCustomLabels
      parameters:
      - 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
      - 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
      - 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
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      - name: property
        in: query
        description: 'Filters responses based on whether a specific property exists, or whose value passes a conditional expression (e.g. `?property=name==C1`). Only the `name` property is supported for core resources. For custom resources, additional supported property values include `status`, `created`, `createdClient`, `createdUser`, `updated`, `updatedClient`, and `updatedUser`. '
        schema:
          type: string
      - name: orderby
        in: query
        description: A comma-separated list of properties by which the returned list of resources will be sorted.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: start
        in: query
        description: 'Indicates the pagination value for the returned list. This value should be obtained from a previous call''s `_page.next` property. Should be omitted for a first page of results. '
        schema:
          type: string
      - name: limit
        in: query
        description: A positive integer, indicating the number of results to limit the response to.
        schema:
          type: integer
      responses:
        '200':
          description: A successful response returns a list of custom labels.
          x-summary: Custom labels retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomLabelsPage'
  /labels/custom/{LABEL_NAME}:
    get:
      tags:
      - Labels
      summary: Retrieve a custom label
      description: '>**NOTE**: For more information on using this operation, see the [labels endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/labels.html) on Experience League.'
      operationId: retrieveCustomLabel
      parameters:
      - name: LABEL_NAME
        in: path
        description: The name of the custom label.
        required: true
        schema:
          type: string
      - 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
      - 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
      - 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
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response returns the details of the retrieved custom label.
          x-summary: Custom label retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomLabelsResponse'
        '404':
          description: No custom label was found for the given name.
          x-summary: Custom label not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomNotFoundError'
    put:
      tags:
      - Labels
      summary: Create or update a custom label
      description: 'You can use this endpoint to create or update a custom label. If the label with the given name does not exist, the custom label will be created. If the label with the given name does exist, the custom label will be updated.


        >**NOTE**: For more information on using this operation, see the [labels endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/labels.html) on Experience League.'
      operationId: createUpdateCustomLabel
      parameters:
      - name: LABEL_NAME
        in: path
        description: The name of the custom label.
        required: true
        schema:
          type: string
      - 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
      - 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
      - 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
      - name: x-sandbox-name
        in: header
        description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomLabelRequest'
        required: true
      responses:
        '200':
          description: If the label name indicated by the request path exists in the system, the existing entity is updated. A successful response returns details of the label, indicating the label was successfully updated.
          x-summary: Custom label updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomLabelsResponse'
        '201':
          description: If the label name indicated by the request path does not exist in the system, a new entity is created. A successful response returns details of the label, indicating the label was successfully created.
          x-summary: Custom label created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomLabelsResponse'
        '400':
          description: There was an error regarding the fields sent in the request payload. This occurs if either of the required fields ("name" or "category") are missing or malformed.
          x-summary: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLabelError'
      x-codegen-request-body-name: body
components:
  schemas:
    PagingPropertiesCustomLabels:
      allOf:
      - $ref: '#/components/schemas/PagingProperties'
      - $ref: '#/components/schemas/_linksPagingCustomLabels'
    LabelsResponse:
      allOf:
      - $ref: '#/components/schemas/CoreLabelBody'
      - $ref: '#/components/schemas/_links'
    BadRequestError:
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        example:
          type: /placeholder/type/uri
          status: 400
          title: BadRequest
    _links:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  description: The URI reference that clients may use to obtain this resource. Typically this URL ends with the `name` or `id` property of the resource.
                  format: uri
                  example: https://platform.adobe.io:443/data/foundation/dulepolicy/policies/core/corepolicy_0003
          description: Contains the URI reference that clients may use to obtain this resource.
    PagingPropertiesCoreLabels:
      allOf:
      - $ref: '#/components/schemas/PagingProperties'
      - $ref: '#/components/schemas/_linksPagingCoreLabels'
    _linksPagingCoreLabels:
      allOf:
      - $ref: '#/components/schemas/_linksPaging'
    NotFoundError:
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        example:
          type: /placeholder/type/uri
          status: 404
          title: NotFound
    CustomLabelsResponse:
      allOf:
      - $ref: '#/components/schemas/CustomLabelBody'
      - $ref: '#/components/schemas/ServiceProperties'
    Error:
      type: object
      properties:
        type:
          type: string
          description: A placeholder value for the error type.
          example: /placeholder/type/uri
        status:
          type: integer
          description: The HTTP status associated with the error.
          format: int32
        title:
          type: string
          description: The error title.
        detail:
          type: string
          description: A description of the error.
    LabelBody:
      type: object
      properties:
        name:
          type: string
          description: A unique name for the label, which also acts as its identifier.
          example: C1
        category:
          type: string
          example: Contract
        friendlyName:
          type: string
          description: A short, friendly name that can be displayed for the label in user interfaces.
          example: Aggregate export only
        description:
          type: string
          description: A description of the label's use case.
          example: Data can only be exported from Adobe Experience Cloud in an aggregated form without including individual or device identifiers.
    PagingProperties:
      type: object
      properties:
        _page:
          type: object
          properties:
            count:
              type: integer
              description: The number of resources returned.
              example: 1
          description: Contains a `count` property for the number of resources returned.
    LabelsPage:
      allOf:
      - $ref: '#/components/schemas/PagingPropertiesCoreLabels'
      - type: object
        properties:
          children:
            type: array
            description: A list of the returned labels.
            items:
              $ref: '#/components/schemas/LabelsResponse'
    CoreNotFoundError:
      allOf:
      - $ref: '#/components/schemas/NotFoundError'
      - type: object
        properties:
          detail:
            type: string
            example: https://platform.adobe.io:443/labels/core/C15 not found
    CustomNotFoundError:
      allOf:
      - $ref: '#/components/schemas/NotFoundError'
      - type: object
        properties:
          detail:
            type: string
            example: https://platform.adobe.io:443/labels/custom/L2 not found
    CoreLabelBody:
      allOf:
      - $ref: '#/components/schemas/LabelBody'
      - type: object
        properties:
          category:
            type: string
            description: The category of the label. Possible values for core labels include `Contract`, `Identity`, and `Sensitive`. Custom labels use the `Custom` category.
            example: Contract
    _linksPagingCustomLabels:
      allOf:
      - $ref: '#/components/schemas/_linksPaging'
    CustomLabelsPage:
      allOf:
      - $ref: '#/components/schemas/PagingPropertiesCustomLabels'
      - type: object
        properties:
          children:
            type: array
            description: A list of the returned labels.
            items:
              $ref: '#/components/schemas/CustomLabelsResponse'
    CustomLabelBody:
      allOf:
      - $ref: '#/components/schemas/LabelBody'
      - type: object
        properties:
          name:
            type: string
            example: L2
          category:
            type: string
            description: The category of the label. Possible values for core labels include `Contract`, `Identity`, and `Sensitive`. Custom labels use the `Custom` category.
            example: Custom
          friendlyName:
            type: string
            example: Purchase History Data
          description:
            type: string
            example: Data containing information on past transactions
    ServiceProperties:
      properties:
        imsOrg:
          type: string
          description: The ID of the IMS Organization which maintains this resource. If the resource is a core resource (defined by Adobe), this value is set to "core".
          example: '{IMS_ORG}'
        sandboxName:
          type: string
          description: The name of the Platform sandbox that contains the resource.
          example: prod
        created:
          type: integer
          description: A timestamp in milliseconds when this resource was originally created.
          format: int64
          example: 1529696681413
        createdClient:
          type: string
          description: The ID of the client that originally created this resource.
          example: '{CLIENT_ID}'
        createdUser:
          type: string
          description: The user that originally created this resource.
          example: '{USER_ID}'
        updated:
          type: integer
          description: A timestamp when this resource was last updated.
          format: int64
          example: 1529697651972
        updatedClient:
          type: string
          description: The ID of the client that last updated this resource.
          example: '{CLIENT_ID}'
        updatedUser:
          type: string
          description: The ID of the user that last updated this resource.
          example: '{USER_ID}'
      allOf:
      - $ref: '#/components/schemas/_links'
    CreateLabelError:
      allOf:
      - $ref: '#/components/schemas/BadRequestError'
      - type: object
        example:
          type: string
          detail: 'Unable to parse LabelRequest: No usable value for category. Did not find value which can be converted into java.lang.String.'
    _linksPaging:
      type: object
      properties:
        _links:
          type: object
          properties:
            _page:
              type: object
              properties:
                href:
                  type: string
                  description: The URL template.
                  format: uri
                templated:
                  type: string
                  description: When present and set to `true`, indicates that this is a templated URL.
          description: Contains a templated URL for clients to obtain this resource.
    CustomLabelRequest:
      allOf:
      - $ref: '#/components/schemas/LabelBody'
      - type: object
        properties:
          category:
            type: string
            description: The category of the label. Must be set to `Custom` for custom labels.
            example: Custom
x-original-swagger-version: '2.0'