openapi: 3.2.0
info:
  title: Segmentation Service Previews API
  description: "\nAdobe Experience Platform Segmentation Service provides a user interface and RESTful API that allows you to create audiences through segment definitions or other sources from your Real-Time Customer Profile data. These audiences are centrally configured and maintained on Platform, and are readily accessible by any Adobe solution. Use the Segmentation Service API to programmatically integrate the service's various functionalities into your experience application, providing RESTful endpoints for managing audiences, segment definitions, segment jobs, exports, schedules, and more.\n- **Related documentation**:\n    - [Segmentation Service documentation](https://www.adobe.com/go/segmentation-overview-en)\n\n- **Visualize API calls with Postman (a free, third-party software)**:\n    - [Segmentation Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Segmentation%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/core/ups\n  - Example of a complete path: https://<span>platform.adobe.io/data/core/ups/segment/definitions\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](https://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/core/ups
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Previews
  description: Previews provide paginated lists of qualifying profiles for a segment definition. More information about using this set of endpoints can be found in the [previews and estimates endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/segmentation/api/previews-and-estimates.html)
paths:
  /preview:
    post:
      tags:
      - Previews
      summary: Create a preview job
      operationId: createPreview
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/content-type'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      requestBody:
        description: '- **predicateExpression**: The predicate expression that is to be evaluated.

          - **predicateType**: (Default: PQL) The only value that is available to use for this is PQL for now.

          - **predicateModel**: (Default: xdm.model.profile) The model against which this predicate is to be evaluated. Please note that ''touchpoint'' is not treated as model as it can be associated with any of the models like profile.

          - **graphType**: The graph type that you want to get the cluster from. Possible values are \"none\" (perform no identity stitching) and \"pdg\" (perform identity stitching based on your private identity graph).'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePreviewRequest'
        required: true
      responses:
        201:
          x-summary: Success
          description: The preview job was successfully posted.
          headers:
            X-Location:
              description: The HREF to the profile preview.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewQueryResponse'
        403:
          x-summary: Missing access permissions
          description: Access is forbidden.
          content: {}
        503:
          x-summary: Service unavailable
          description: The service is unavailable.
          content: {}
      x-codegen-request-body-name: body
  /preview/{PREVIEW_ID}:
    get:
      tags:
      - Previews
      summary: Retrieve the results of a preview job
      operationId: retrievePreview
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: PREVIEW_ID
        in: path
        description: The ID of the preview job.
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: The offset of the page.
        schema:
          type: string
        example: offset=10200
      - name: limit
        in: query
        description: The number of entries that should be present on a page. If not specified, this value will be 1000.
        schema:
          type: integer
        example: 100
      responses:
        200:
          x-summary: Success
          description: The results of the preview job have been successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewResponse'
        403:
          x-summary: Missing access permissions
          description: Access is forbidden.
          content: {}
        404:
          x-summary: Not found
          description: The preview job was not found.
          content: {}
        503:
          x-summary: Service unavailable
          description: The service is unavailable.
          content: {}
    delete:
      tags:
      - Previews
      summary: Cancel or delete a preview job
      operationId: deletePreview
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - name: PREVIEW_ID
        in: path
        description: The ID of the preview job.
        required: true
        schema:
          type: string
      responses:
        200:
          x-summary: Success
          description: The preview job was successfully cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        403:
          x-summary: Missing access permissions
          description: Access is forbidden.
          content: {}
        404:
          x-summary: Not found
          description: The preview job was not found.
          content: {}
        503:
          x-summary: Service unavailable
          description: The service is unavailable.
          content: {}
components:
  schemas:
    PreviewResults:
      type: object
      properties:
        objectId:
          type: string
          description: A unique identifier of the XDM object.
        _href:
          type: string
          description: The profile access link to the contents of an XDM object.
        relatedObjects:
          type: array
          description: A list of related objectIds.
          items:
            $ref: '#/components/schemas/IndividualPreview'
    PreviewQueryResponse:
      required:
      - previewExecutionId
      - previewQueryId
      - previewQueryStatus
      - state
      type: object
      properties:
        previewQueryId:
          type: string
          description: An ID that can be used for debugging purposes.
          example: 4a45e853-ac91-4bb7-a426-150937b6af5c
        state:
          type: string
          description: The state of the preview job.
          example: RUNNING
        previewQueryStatus:
          type: string
          description: The state of the preview job.
          example: RUNNING
        previewId:
          type: string
          description: The ID for the preview job. You can use this ID to retrieve results of the preview job.
          example: MDoyOjRhNDVlODUzLWFjOTEtNGJiNy1hNDI2LTE1MDkzN2I2YWY1Yzo0Mg
        previewExecutionId:
          type: integer
          format: int32
          example: 42
    PreviewResponse:
      type: object
      properties:
        page:
          type: object
          description: The page information of the current response entity.
        link:
          type: string
          description: The HREF link to the preview.
        state:
          type: string
          description: The execution state of the query.
        results:
          type: array
          description: The list of end customer entities.
          items:
            $ref: '#/components/schemas/PreviewResults'
      description: The end customer entity response, with current page information and next page link.
    IndividualPreview:
      type: object
      properties:
        objectId:
          type: string
          description: A unique identifier of XDM object.
        _href:
          type: string
          description: The profile access link to the contents of an XDM object.
    MessageResponse:
      required:
      - message
      - status
      type: object
      properties:
        status:
          type: boolean
        message:
          type: string
    CreatePreviewRequest:
      type: object
      properties:
        predicateExpression:
          type: string
          description: The predicate expression that is to be evaluated.
          example: xEvent.metrics.commerce.abandons.value > 0
        predicateType:
          type: string
          description: The predicate expression type. By default, this is PQL.
          example: pql/text
        predicateModel:
          type: string
          description: The model in which the predicate is evaluated against. By default, this value is "xdm.model.profile".
          example: _xdm.context.profile
        graphType:
          type: string
          description: The graph type that you want to get the cluster from. If the value is `pdg`, identity stitching will be done based on your private identity graph. If the value is `none`, no identity stitching will be done.
          example: pdg
          enum:
          - pdg
          - none
  parameters:
    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. 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