Adobe Suite Policy evaluation API

openapi: 3.2.0
info:
  title: Policy Service Policy evaluation 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: Policy evaluation
  description: The policy evaluation endpoints allow you to test a marketing action against specific labels or against datasets and fields to check for policy violations.
paths:
  /marketingActions/core/{MARKETING_ACTION_NAME}/constraints:
    get:
      tags:
      - Policy evaluation
      summary: Evaluate a core marketing action based on data usage labels
      description: 'This call returns a set of constraints that would govern an attempt to perform the given marketing action on a hypothetical source of data containing specific data usage labels.


        You can also evaluate a marketing action based on the labels contained in an actual dataset in your data stores. See the POST method for this endpoint for more information.


        >**NOTE**: For more information on using this operation, see the [policy evaluation endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/evaluation.html) on Experience League.'
      operationId: evaluateCoreMarketingActionUsingLabels
      parameters:
      - name: MARKETING_ACTION_NAME
        in: path
        description: The name of the marketing action to test data usage labels against.
        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
      - name: duleLabels
        in: query
        description: A comma-separated list of data usage labels that would be present on data that you want to test for policy violations.
        required: true
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: includeDraft
        in: query
        description: If true, the system checks for policy violations among policies with `DRAFT` status as well as `ENABLED` status. Otherwise, only `ENABLED` policies are checked.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A successful response returns the constraints on attempting to perform this marketing action on data bearing the given set of data usage labels, including the set of policies that would be violated.
          x-summary: Marketing action constraints retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoreLabelsConstraints'
        '404':
          description: No marketing action was found for the given name.
          x-summary: Marketing action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoreMarketingActionNotFound'
    post:
      tags:
      - Policy evaluation
      summary: Evaluate a core marketing action based on datasets and/or fields
      description: 'This call returns a set of constraints that would govern an attempt to perform the given marketing action on an existing data source in Platform. The source data (typically a dataset) is specified by the `entityType` and `entityId` of the elements in the request body. In the case of a dataset entity, a set of fields may also be specified in the `entityMeta` to indicate that only those fields from that dataset should be used in the evaluation. The returned constraints take the form of a set of policies that would be violated by attempting the marketing action on the dataset(s) and/or field(s).


        You can also evaluate a marketing action based on a defined set of usage labels instead of testing against an actual data source. See the GET method for this endpoint for more information.


        >**NOTE**: For more information on using this operation, see the [policy evaluation endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/evaluation.html) on Experience League.'
      operationId: evaluateCoreMarketingActionUsingDatasets
      parameters:
      - name: MARKETING_ACTION_NAME
        in: path
        description: The name of the marketing action to test against datasets or fields.
        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
      - name: Content-Type
        in: header
        description: The type of content being sent in the body of the request. In POST, PUT, or PATCH requests to the Policy Service API, the value must be set to `application/json`.
        required: true
        schema:
          type: string
      - name: includeDraft
        in: query
        description: If true, the system checks for policy violations among policies with `DRAFT` status as well as `ENABLED` status. Otherwise, only `ENABLED` policies are checked.
        schema:
          type: boolean
          default: false
      requestBody:
        description: An array that lists the entities for which to retrieve labels. This can include dataset IDs and individual fields within those datasets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/EntityLabelRequest'
        required: true
      responses:
        '200':
          description: A successful response returns the constraints on attempting to perform this marketing action on the given set of datasets and/or fields, including the set of policies that would be violated.
          x-summary: Marketing action dataset constraints retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoreDatasetConstraintResponse'
        '400':
          description: One or more of the required fields in the request body were either missing or malformed.
          x-summary: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketingActionConstraintsError'
        '404':
          description: No marketing action was found for the given name.
          x-summary: Marketing action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoreMarketingActionNotFound'
      x-codegen-request-body-name: body
  /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints:
    get:
      tags:
      - Policy evaluation
      summary: Evaluate a custom marketing action based on data usage labels
      description: 'This call returns a set of constraints that would govern an attempt to perform the given marketing action on a hypothetical source of data containing specific data usage labels.


        You can also evaluate a marketing action based on the labels contained in an actual dataset in your data stores. See the POST method for this endpoint for more information.


        >**NOTE**: For more information on using this operation, see the [policy evaluation endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/evaluation.html) on Experience League.'
      operationId: evaluateCustomMarketingActionUsingLabels
      parameters:
      - name: MARKETING_ACTION_NAME
        in: path
        description: The name of the marketing action to test data usage labels against.
        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
      - name: duleLabels
        in: query
        description: A comma-separated list of data usage labels that would be present on data that you want to test for policy violations.
        required: true
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: includeDraft
        in: query
        description: If true, the system checks for policy violations among policies with `DRAFT` status as well as `ENABLED` status. Otherwise, only `ENABLED` policies are checked.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A successful response returns the constraints on attempting to perform this marketing action on data bearing the given set of data usage labels, including the set of policies that would be violated.
          x-summary: Marketing action constraints retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomLabelsConstraints'
        '404':
          description: No marketing action was found for the given name.
          x-summary: Marketing action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomMarketingActionNotFound'
    post:
      tags:
      - Policy evaluation
      summary: Evaluate a custom marketing action based on datasets and/or fields
      description: 'This call returns a set of constraints that would govern an attempt to perform the given marketing action on an existing data source in Platform. The source data (typically a dataset) is specified by the "entityType" and "entityId" of the elements in the request body. In the case of a dataset entity, a set of fields may also be specified in the "entityMeta" to indicate that only those fields from that dataset should be used in the evaluation. The returned constraints take the form of a set of policies that would be violated by attempting the marketing action on the dataset(s) and/or field(s).


        You can also evaluate a marketing action based on a defined set of usage labels instead of testing against an actual data source. See the GET method for this endpoint for more information.


        >**NOTE**: For more information on using this operation, see the [policy evaluation endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/evaluation.html) on Experience League.'
      operationId: evaluateCustomMarketingActionUsingDatasets
      parameters:
      - name: MARKETING_ACTION_NAME
        in: path
        description: The name of the marketing action to test against datasets or fields.
        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
      - name: Content-Type
        in: header
        description: The type of content being sent in the body of the request. In POST, PUT, or PATCH requests to the Policy Service API, the value must be set to `application/json`.
        required: true
        schema:
          type: string
      - name: includeDraft
        in: query
        description: If true, the system checks for policy violations among policies with `DRAFT` status as well as `ENABLED` status. Otherwise, only `ENABLED` policies are checked.
        schema:
          type: boolean
          default: false
      requestBody:
        description: An array that lists the entities for which to retrieve labels. This can include dataset IDs and individual fields within those datasets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/EntityLabelRequest'
        required: true
      responses:
        '200':
          description: A successful response returns the constraints on attempting to perform this marketing action on the given set of datasets and/or fields, including the set of policies that would be violated.
          x-summary: Marketing action dataset constraints retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDatasetConstraintResponse'
        '400':
          description: A bad request; see response body for details
          x-summary: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No marketing action was found for the given name
          x-summary: Marketing action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codegen-request-body-name: body
  /bulk-eval:
    post:
      tags:
      - Policy evaluation
      summary: Run multiple policy evaluation jobs in bulk
      description: This endpoint allows you to run a list of policy evaluations in bulk, so you don't have to call the **../{MARKETING_ACTION_NAME}/constraints** endpoint multiple times.
      operationId: bulkEval
      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
      requestBody:
        description: 'An array of policy evaluation jobs to perform in bulk. Each job must evaluate based on one of the following:

          * A set of labels

          * A list of datasets and/or fields within those datasets


          To evaluate a marketing action based on both labels and datasets, you must include two separate jobs for that action: one that includes a **labels** array, and one that contains an **entityList** array.

          >**NOTE**: For more information on using this operation, see the [policy evaluation endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/evaluation.html#bulk) on Experience League.'
        content:
          application/json:
            schema:
              type: array
              example:
              - evalRef: https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting/constraints
                includeDraft: false
                labels:
                - C1
                - C2
                - C3
              - evalRef: https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting/constraints
                includeDraft: false
                entityList:
                - entityType: dataSet
                  entityId: 5b67f4dd9f6e710000ea9da4
                  entityMeta:
                    fields:
                    - address
              items:
                $ref: '#/components/schemas/BulkEvalRequest'
        required: true
      responses:
        '200':
          description: A successful response returns an array of evaluation results; one for each policy evaluation job sent in the request.
          x-summary: Policy evaluation results retrieved successfully
          content:
            application/json:
              schema:
                type: array
                example:
                - status: 200
                  body:
                    timestamp: 1595866566165
                    clientId: '{CLIENT_ID}'
                    userId: '{USER_ID}'
                    imsOrg: '{IMS_ORG}'
                    sandboxName: prod
                    marketingActionRef: https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting
                    duleLabels:
                    - C1
                    - C2
                    - C3
                    violatedPolicies: []
                - status: 200
                  body:
                    timestamp: 1595866566165
                    clientId: '{CLIENT_ID}'
                    userId: '{USER_ID}'
                    imsOrg: '{IMS_ORG}'
                    sandboxName: prod
                    marketingActionRef: https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting
                    duleLabels:
                    - C1
                    - C2
                    discoveredLabels:
                    - entityType: dataset
                      entityId: 5b67f4dd9f6e710000ea9da4
                      dataSetLabels:
                        connection:
                          labels: []
                        dataset:
                          labels:
                          - C1
                          - C2
                        fields: []
                    violatedPolicies:
                    - name: Email Policy
                      status: DRAFT
                      marketingActionRefs:
                      - https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting
                      description: Conditions under which we won't send marketing-based email
                      deny:
                        operator: AND
                        operands:
                        - label: C1
                        - label: C3
                      id: 76131228-7654-11e8-adc0-fa7ae01bbebc
                      imsOrg: '{IMS_ORG}'
                      created: 1529696681413
                      createdClient: '{CLIENT_ID}'
                      createdUser: '{USER_ID}'
                      updated: 1529697651972
                      updatedClient: '{CLIENT_ID}'
                      updatedUser: '{USER_ID}'
                      _links:
                        self:
                          href: ./76131228-7654-11e8-adc0-fa7ae01bbebc
                items:
                  $ref: '#/components/schemas/BulkEvalResponse'
        '400':
          description: One or more of the required fields in the request body were either missing or malformed. This error typically occurs when one of the evaluation jobs in the payload contains both a **labels** array and an **entityList** array.
          x-summary: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketingActionConstraintsError'
      x-codegen-request-body-name: body
components:
  schemas:
    PolicyBody:
      type: object
      properties:
        name:
          type: string
          description: The name of the policy
          example: Email Policy
        status:
          type: string
          description: The status of the policy
          example: ENABLED
          enum:
          - DRAFT
          - ENABLED
          - DISABLED
        marketingActionRefs:
          type: array
          description: List of marketing action URI references to which this policy applies.
          example:
          - https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting
          items:
            type: string
            format: uri
        description:
          type: string
          description: A description of what this policy enforces. Specifically, the reasoning behind the denial of these marketing actions in the presence of the data usage labels.
          example: Conditions under which we won't send marketing-based email
        deny:
          $ref: '#/components/schemas/PolicyExpression'
    BulkEvalRequest:
      required:
      - evalRef
      type: object
      properties:
        evalRef:
          type: string
          description: The constraints URL to be evaluated. Should be of the form `../marketingActions/core/{MARKETING_ACTION_NAME}/constraints`.  This evalRef provides a way to specify the marketing action name as well as whether it is a core or custom marketing action. Only the portion of this URL after the `/marketingActions` component is significant; any prefix to this is ignored.
          example: https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/core/emailTargeting/constraints
        includeDraft:
          type: boolean
          description: If true, the system checks for policy violations among policies with "DRAFT" status as well as "ENABLED" status. Otherwise, only "ENABLED" policies are checked.
          default: false
        labels:
          type: array
          description: List of labels to evaluate against the constraints. Any one request may contain either `labels` or `entityList`, not both.
          example:
          - C1
          - C2
          - C3
          items:
            type: string
        entityList:
          type: array
          description: List of entities on which to retrieve labels in order to perform this evaluation. Any one request may contain either `labels` or `entityList`, not both.
          items:
            $ref: '#/components/schemas/BulkEntityLabelRequest'
      description: An individual request to perform policy evaluation as part of a bulk of such requests.
    BadRequestError:
      allOf:
      - $ref: '#/components/schemas/Error'
      - type: object
        example:
          type: /placeholder/type/uri
          status: 400
          title: BadRequest
    CoreLabelsConstraints:
      allOf:
      - $ref: '#/components/schemas/CoreMarketingActionConstraints'
      - $ref: '#/components/schemas/LabelsConstraints'
    DuleLabelsList:
      required:
      - labels
      type: object
      properties:
        labels:
          type: array
          description: A list of data usage labels discovered from the entity.
          example:
          - C1
          - C3
          - C7
          items:
            type: string
    PolicyExpression:
      type: object
      properties:
        label:
          type: string
          description: The name of a single data usage label that applies to the policy.
          example: C1
        operator:
          type: string
          description: "Indicates the conditional relationship between the labels provided in the sibling operands array. Accepted values are:\n  \n  - `OR`: The expression resolves to true if any of the labels in the operands array are present.\n  - `AND`: The expression only resolves to true if all of the labels in the operands array are present."
          example: AND
          enum:
          - AND
          - OR
        operands:
          type: array
          description: An array of objects, with each object representing either a single `label` or an additional pair of `operator` and `operands` properties. The presence of the labels and/or operations in an `operands` array resolves to true or false based on the value of its sibling operator property.
          example:
          - label: C1
          - label: C3
          items:
            $ref: '#/components/schemas/PolicyExpression'
      description: A boolean expression to be evaluated over the presence of data usage labels, referred to as a "policy expression". Note that a policy expression **must** consist of **either** a label **or** an operator and operands. Each operand in turn is itself a policy expression. You cannot specify both a label and an operator/operand in combination. See the [Policy Service API guide](https://experienceleague.adobe.com/docs/experience-platform/data-governance/api/policies.html?lang=en#create-policy) for more details on how to configure this property.
      example:
        operator: AND
        operands:
        - label: C1
        - operator: OR
          operands:
          - label: C3
          - label: C7
    FieldsLabels:
      allOf:
      - required:
        - path
        type: object
        properties:
          path:
            type: st

# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adobe-suite/refs/heads/main/openapi/adobe-suite-policy-evaluation-api-openapi.yml