openapi: 3.2.0
info:
  title: Segmentation Service Segment definitions 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: Segment definitions
  description: Segment definitions include a Profile Query Language (PQL) statement that defines which profiles will be part of an audience. More information about using this set of endpoints can be found in the [segment definitions endpoint guide](https://experienceleague.adobe.com/docs/experience-platform/segmentation/api/segment-definitions.html).
paths:
  /segment/definitions:
    get:
      tags:
      - Segment definitions
      summary: List segment definitions
      operationId: listSegmentDefinitions
      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: x-request-id
        in: header
        description: A unique ID that can be used to track a request.
        schema:
          type: string
        example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
      - name: start
        in: query
        description: The page offset, as per created time of resource.
        schema:
          type: integer
          format: int64
        example: 109103839
      - name: limit
        in: query
        description: The maximum size of the page.
        schema:
          type: integer
        example: 10
      - name: page
        in: query
        description: The page number.
        schema:
          type: integer
        example: 0
      - name: sort
        in: query
        description: The parameters used to sort the results.
        schema:
          type: string
        example: sort=name:asc,internalId:desc
      responses:
        200:
          x-summary: Success
          description: A list of segment definitions is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDefinition'
        403:
          x-summary: Missing access permissions
          description: Access is forbidden.
          content: {}
        503:
          x-summary: Service unavailable
          description: The service is unavailable.
          content: {}
    post:
      tags:
      - Segment definitions
      summary: Create a segment definition
      operationId: createSegmentDefinition
      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'
      - name: x-request-id
        in: header
        description: A unique ID that can be used to track a request.
        schema:
          type: string
        example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
      requestBody:
        description: '- **name**: The name of the segment definition. This value must be unique.

          - **description**: A description of the segment definition.

          - **expression**: The PQL expression of the segment definition. Contains the PQL type, format, as well as the value of the PQL query.

          - **schema**: - The schema class for the segment definition.

          - **evaluationInfo**: - An object that determines the type of segment definition that''s created. If `batch` is set to `true`, it will be a segment definition evaluated using batch segmentation. If `continuous` is set to `true`, it will be a segment definition evaluated using streaming segmentation. If `synchronous` is set to `true`, it will be a segment definition evaluated using edge segmentation. By default, a segment definition evaluated using batch segmentation will be created.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSegmentDefinition'
            examples:
              pql/text:
                value:
                  name: Sample segment definition
                  description: Sample description
                  expression:
                    type: PQL
                    format: pql/text
                    value: workAddress.country = "US"
                  evaluationInfo:
                    batch:
                      enabled: true
                    continuous:
                      enabled: false
                    synchronous:
                      enabled: false
                  schema:
                    name: _xdm.context.profile
                  payloadSchema: string
              pql/json:
                value:
                  name: Sample segment definition
                  description: Sample description
                  expression:
                    type: PQL
                    format: pql/json
                    value: '{"nodeType":"fnApply","fnName":"=","params":[{"nodeType":"fieldLookup","fieldName":"a","object":{"nodeType":"parameterReference","position":1}},{"nodeType":"fieldLookup","fieldName":"b","object":{"nodeType":"parameterReference","position":1}}]}'
                  evaluationInfo:
                    batch:
                      enabled: true
                    continuous:
                      enabled: false
                    synchronous:
                      enabled: false
                  schema:
                    name: _xdm.context.profile
                  payloadSchema: string
        required: true
      responses:
        200:
          x-summary: Success
          description: The segment definition was successfully posted.
          headers:
            X-Location:
              description: The URL of the segment definition.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDefinition'
              examples:
                pql/text:
                  value:
                    id: 54669488-03ab-4e0d-a694-37fe49e32be8
                    imsOrgId: '{ORG_ID}'
                    mergePolicyId: 5ed35fd8-6eeb-4ad2-bed9-43e695b8ac0b
                    profileInstanceId: ups
                    name: Sample segment definition
                    description: Sample description
                    expression:
                      type: PQL
                      format: pql/text
                      value: workAddress.country = "US"
                    evaluationInfo:
                      batch:
                        enabled: true
                      continuous:
                        enabled: false
                      synchronous:
                        enabled: false
                    schema:
                      name: _xdm.context.profile
                    dataGovernancePolicy:
                      excludeOptOut: true
                    creationTime: 0
                    updateEpoch: 1579292094
                    updateTime: 1579292094000
                    payloadSchema: string
                pql/json:
                  value:
                    id: 54669488-03ab-4e0d-a694-37fe49e32be8
                    imsOrgId: '{ORG_ID}'
                    mergePolicyId: 5ed35fd8-6eeb-4ad2-bed9-43e695b8ac0b
                    profileInstanceId: ups
                    name: Sample segment definition
                    description: Sample description
                    expression:
                      type: PQL
                      format: pql/json
                      value: '{"nodeType":"fnApply","fnName":"=","params":[{"nodeType":"fieldLookup","fieldName":"a","object":{"nodeType":"parameterReference","position":1}},{"nodeType":"fieldLookup","fieldName":"b","object":{"nodeType":"parameterReference","position":1}}]}'
                    evaluationInfo:
                      batch:
                        enabled: true
                      continuous:
                        enabled: false
                      synchronous:
                        enabled: false
                    schema:
                      name: _xdm.context.profile
                    dataGovernancePolicy:
                      excludeOptOut: true
                    creationTime: 0
                    updateEpoch: 1579292094
                    updateTime: 1579292094000
                    payloadSchema: string
        400:
          x-summary: Error
          description: An invalid segment definition was posted.
          content: {}
        403:
          x-summary: Missing access permissions
          description: Access is forbidden.
          content: {}
        422:
          x-summary: Already exists
          description: The segment definition already exists. In order to update a segment definition, use the PATCH operation instead.
          content: {}
        503:
          x-summary: Service unavailable
          description: The service is unavailable.
          content: {}
      x-codegen-request-body-name: body
  /segment/definitions/{SEGMENT_ID}:
    get:
      tags:
      - Segment definitions
      summary: Retrieve a segment definition
      operationId: retrieveSegmentDefinitionById
      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: x-request-id
        in: header
        description: A unique ID that can be used to track a request.
        schema:
          type: string
        example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
      - name: SEGMENT_ID
        in: path
        description: The ID of the segment definition.
        required: true
        schema:
          type: string
      responses:
        200:
          x-summary: Success
          description: The segment definition was successfully returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDefinition'
        403:
          x-summary: Missing access permissions
          description: Access is forbidden.
          content: {}
        404:
          x-summary: Not found
          description: The segment definition was not found.
          content: {}
        503:
          x-summary: Service unavailable
          description: The service is unavailable.
          content: {}
    delete:
      tags:
      - Segment definitions
      summary: Delete a segment definition
      operationId: deleteSegmentDefinition
      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: x-request-id
        in: header
        description: A unique ID that can be used to track a request.
        schema:
          type: string
        example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
      - name: SEGMENT_ID
        in: path
        description: The ID of the segment definition.
        required: true
        schema:
          type: string
      responses:
        200:
          x-summary: Success
          description: The segment definition was successfully deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        403:
          x-summary: Missing access permissions
          description: Access is forbidden.
          content: {}
        503:
          x-summary: Service unavailable
          description: The service is unavailable.
          content: {}
    patch:
      tags:
      - Segment definitions
      summary: Overwrite a segment definition.
      operationId: patchSegmentDefinition
      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'
      - name: x-request-id
        in: header
        description: A unique ID that can be used to track a request.
        schema:
          type: string
        example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
      - name: SEGMENT_ID
        in: path
        description: The ID of the segment definition.
        required: true
        schema:
          type: string
      requestBody:
        description: '- **name**: The name of the segment definition. This value must be unique.

          - **description**: A description of the segment definition.

          - **expression**: The PQL expression of the segment definition. Contains the PQL type, format, as well as the value of the PQL query.

          - **schema**: - The schema class for the segment definition.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentDefinition'
        required: true
      responses:
        200:
          x-summary: Success
          description: The segment definition was successfully updated.
          headers:
            X-Location:
              description: HREF to the segment definition
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDefinition'
        400:
          x-summary: Error
          description: The segment definition is invalid.
          content: {}
        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
  /segment/definitions/bulk-get:
    post:
      tags:
      - Segment definitions
      summary: Retrieve multiple segment definitions using multiple segment definition IDs
      operationId: bulkGetSegmentDefinitions
      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: An array of the segment definition IDs that you are trying to retrieve.
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        example: 54669488-03ab-4e0d-a694-37fe49e32be8
            example:
              ids:
              - id: 54669488-03ab-4e0d-a694-37fe49e32be8
              - id: c527dc3f-07fe-4b96-be4e-23f38e734ff8
        required: true
      responses:
        207:
          x-summary: Success
          description: The details of each segment definition are returned. The sample response has been truncated to show only the details for the first segment definition.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    properties:
                      54669488-03ab-4e0d-a694-37fe49e32be8:
                        type: object
                        properties:
                          id:
                            type: string
                            example: 54669488-03ab-4e0d-a694-37fe49e32be8
                          schema:
                            type: object
                            properties:
                              name:
                                type: string
                                example: _xdm.context.profile
                          profileInstanceId:
                            type: string
                            example: ups
                          imsOrgId:
                            type: string
                            example: '{ORG_ID}'
                          sandbox:
                            type: object
                            properties:
                              sandboxId:
                                type: string
                                example: 28e74200-e3de-11e9-8f5d-7f27416c5f0d
                              sandboxName:
                                type: string
                                example: prod
                              type:
                                type: string
                                example: production
                              default:
                                type: boolean
                                example: true
                          name:
                            type: string
                            example: Sample segment definition 1
                          description:
                            type: string
                            example: Sample segment definition description
                          expression:
                            type: object
                            properties:
                              type:
                                type: string
                                example: PQL
                              format:
                                type: string
                                example: pql/text
                              value:
                                type: string
                                example: workAddress.country = "US"
                          evaluationInfo:
                            type: object
                            properties:
                              batch:
                                type: object
                                properties:
                                  enabled:
                                    type: boolean
                                    example: true
                              continuous:
                                type: object
                                properties:
                                  enabled:
                                    type: boolean
                                    example: false
                              synchronous:
                                type: object
                                properties:
                                  enabled:
                                    type: boolean
                                    example: false
                          dataGovernancePolicy:
                            type: object
                            properties:
                              excludeOptOut:
                                type: boolean
                                example: true
                          creationTime:
                            type: integer
                            example: 0
                          updateEpoch:
                            type: integer
                            example: 1579292094
                          updateTime:
                            type: integer
                            example: 1579292094000
                      c527dc3f-07fe-4b96-be4e-23f38e734ff8:
                        type: object
                        properties:
                          id:
                            type: string
                            example: c527dc3f-07fe-4b96-be4e-23f38e734ff8
                          schema:
                            type: object
                            properties:
                              name:
                                type: string
                                example: _xdm.context.profile
                          profileInstanceId:
                            type: string
                            example: ups
                          imsOrgId:
                            type: string
                            example: '{ORG_ID}'
                          sandbox:
                            type: object
                            properties:
                              sandboxId:
                                type: string
                                example: 28e74200-e3de-11e9-8f5d-7f27416c5f0d
                              sandboxName:
                                type: string
                                example: prod
                              type:
                                type: string
                                example: production
                              default:
                                type: boolean
                                example: true
                          name:
                            type: string
                            example: Sample segment definition 2
                          description:
                            type: string
                            example: Another sample segment definition description
                          expression:
                            type: object
                            properties:
                              type:
                                type: string
                                example: PQL
                              format:
                                type: string
                                example: pql/text
                              value:
                                type: string
                                example: workAddress.country = \"US\"
                          evaluationInfo:
                            type: object
                            properties:
                              batch:
                                type: object
                                properties:
                                  enabled:
                                    type: boolean
                                    example: true
                              continuous:
                                type: object
                                properties:
                                  enabled:
                                    type: boolean
                                    example: false
                              synchronous:
                                type: object
                                properties:
                                  enabled:
                                    type: boolean
                                    example: false
                          dataGovernancePolicy:
                            type: object
                            properties:
                              excludeOptOut:
                                type: boolean
                                example: true
                          creationTime:
                            type: integer
                            example: 0
                          updateEpoch:
                            type: integer
                            example: 1579292094
                          updateTime:
                            type: integer
                            example: 1579292094000
      x-codegen-request-body-name: body
  /segment/conversion:
    post:
      tags:
      - Segment definitions
      summary: Convert a segment definition
      description: This endpoint converts a segment definition from pql/text to pql/json or from pql/json to pql/text.
      operationId: convertSegmentDefinition
      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'
      - name: x-request-id
        in: header
        description: A unique ID that can be used to track a request.
        schema:
          type: string
        example: jRot0Q3pgFi2lmLecebqHGTfnApAwVnQ
      requestBody:
        description: '- **name**: The name of the segment definition. This value must be unique.

          - **description**: A description of the segment definition.

          - **expression**: The PQL expression of the segment definition. Contains the PQL type, format, as well as the value of the PQL query.

          - **schema**: - The schema class for the segment definition.'
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/SegmentDefinition'
        required: true
      responses:
        200:
          x-summary: Success
          description: The segment definition was successfully converted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentDefinition'
        400:
          x-summary: Error
          description: An invalid segment definition was posted.
          content: {}
        409:
          x-summary: Conflict
          description: Conflict. An entity with the specified ID already exists in the system.
          content: {}
        429:
          x-summary: Too many requests
          description: Too many requests. Please try again in a few minutes.
          content: {}
        503:
          x-summary: Service unavailable
          description: The service is unavailable.
          content: {}
      x-codegen-request-body-name: body
components:
  schemas:
    CreateSegmentDefinition:
      required:
      - name
      - schema
      - expression
      type: object
      properties:
        name:
          type: string
          description: The unique name for the segment definition.
          example: People who ordered in the last 30 days
        description:
          type: string
          description: An optional description to describe the segment definition.
          example: Last 30 days
        profileInstanceId:
          type: string
          example: ups
        expression:
          type: object
          properties:
            type:
              type: string
              example: PQL
            format:
              type: string
              example: pql/text
            value:
              type: string
              example: workAddress.country = \"US\"
        evaluationInfo:
          type: object
          properties:
            batch:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: true
            continuous:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: false
            synchronous:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: false
        schema:
          type: object
          properties:
            name:
              type: string
              example: _xdm.context.profile
        payloadSchema:
          type: string
          example: string
    Expression:
      type: object
      properties:
        type:
          type: string
          description: The type of the expression.
          example: PQL
          enum:
          - PQL
          - ARL
        format:
          type: string
          description: The format of the expression.
          example: pql/text
          enum:
          - pql/text
          - pql/json
        value:
          type: string
          description: The query string, written as PQL.
          example: workAddress.country = "US"
      description: Information regarding the segment definition's expression.
    SegmentDefinition:
      required:
      - expression
      - name
      - schema
      type: object
      properties:
        id:
          type: string
          example: 54669488-03ab-4e0d-a694-37fe49e32be8
        imsOrgId:
          type: string
          description: The ID of the organization related to the segment definition.
          example: '{ORG_ID}'
        name:
          type: string
          description: A unique name for the segment definition.
          example: People who ordered in the last 30 days
        mergePolicyId:
          type: string
          description: The ID of the merge policy.
          example: 5ed35fd8-6eeb-4ad2-bed9-43e695b8ac0b
        profileInstanceId:
          type: string
          description: The ID of the profile instance provided.
          example: ups
        description:
          type: string
          description: A brief description about the segment definition.
          example: Last 30 days
        expression:
          $ref: '#/components/schemas/Expression'
        schema:
          $ref: '#/components/schemas/SchemaClass'
        evaluationInfo:
          type: object
          properties:
            batch:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: true
              description: If this property is marked as enabled, the audience will be evaluated using batch segmentation.
            continuous:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: false
              description: If this property is marked as enabled, the audience will be evaluated using streaming segmentation.
            synchronous:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: false
              description: If this property is marked as enabled, the audience will be evaluated using edge segmentation.
          description: An object that describes how the audience is evaluated.
        payloadSchema:
          type: string
        dataGovernancePolicy:
          type: object
          properties:
            excludeOptOut:
              type: boolean
              example: true
        creationTime:
          type: integer
          description: The timestamp, as unix time in milliseconds, for when the segment definition was created.
          format: int64
        updateTime:
          type: integer
          description: The timestamp, as unix time in milliseconds, for when the segment definition was last updated.
          format: int64
        updateEpoch:
          type: integer
          description: The timestamp, as unix time in seconds, for when the segment definition was last updated.
          format: int64
    MessageResponse:
      required:
      - message
      - status
      type: object
      properties:
        status:
          type: boolean
        message:
          type: string
    SchemaClass:
      required:
      - name
      type: object
      properties:
        name:
          type: string
          description: The ID of the schema class.
          example: _xdm.context.profile
      description: The schema class.
  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