Adobe Suite Segments API

openapi: 3.2.0
info:
  description: The endpoints described here are routed through analytics.adobe.io.
  title: Adobe Analytics Segments API
  version: '2.0'
servers:
- url: https://analytics.adobe.io/api
tags:
- name: Segments
paths:
  /{globalCompanyId}/segments:
    get:
      tags:
      - Segments
      summary: Retrieve all segments
      description: ''
      operationId: segments_getSegments
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: rsids
        in: query
        description: Filter list to only include segments tied to specified RSID list (comma-delimited)
        required: false
        schema:
          type: string
      - name: segmentFilter
        in: query
        description: Filter list to only include segments in the specified list (comma-delimited list of IDs)
        required: false
        schema:
          type: string
      - name: locale
        in: query
        description: Locale
        required: false
        schema:
          type: string
          default: en_US
      - name: name
        in: query
        description: Filter list to only include segments that contains the Name
        required: false
        schema:
          type: string
      - name: tagNames
        in: query
        description: Filter list to only include segments that contains one of the tags
        required: false
        schema:
          type: string
      - name: filterByPublishedSegments
        in: query
        description: Filter list to only include segments where the published field is set to one of the allowable values (all, true, false).
        required: false
        schema:
          type: string
          enum:
          - all
          - 'true'
          - 'false'
          default: all
      - name: limit
        in: query
        description: Number of results per page
        required: false
        schema:
          type: integer
          default: 10
      - name: page
        in: query
        description: Page number (base 0 - first page is "0")
        required: false
        schema:
          type: integer
          default: 0
      - name: sortDirection
        in: query
        description: Sort direction (ASC or DESC
        required: false
        schema:
          type: string
          default: ASC
      - name: sortProperty
        in: query
        description: Property to sort by (name, modified_date, id is currently allowed)
        required: false
        schema:
          type: string
          default: id
      - name: expansion
        in: query
        description: Comma-delimited list of additional segment metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - reportSuiteName
            - ownerFullName
            - modified
            - tags
            - compatibility
            - definition
            - publishingStatus
            - definitionLastModified
            - categories
          enum:
          - reportSuiteName
          - ownerFullName
          - modified
          - tags
          - compatibility
          - definition
          - publishingStatus
          - definitionLastModified
          - categories
      - name: includeType
        in: query
        description: Include additional segments not owned by user. The "all" option takes precedence over "shared"
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - shared
            - all
            - templates
          enum:
          - shared
          - all
          - templates
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSegmentResponseItem'
        '400':
          description: Unable to retrieve list of segments shared with user
        '401':
          description: Owner filter error; user specified is not in the same company as the requesting user
        '403':
          description: Requesting non-shared segments for other users is restricted to admin users
        '500':
          description: External API error; Segment retrieval failed
    post:
      tags:
      - Segments
      summary: Create a segment
      description: ''
      operationId: segments_createSegment
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: locale
        in: query
        description: Locale. Valid values include 'en_US', 'fr_FR', 'ja_JP', 'de_DE', 'es_ES', 'ko_KR', 'pt_BR', 'zh_CN', and 'zh_TW'.
        required: false
        schema:
          type: string
          default: en_US
      - name: expansion
        in: query
        description: Comma-delimited list of additional segment metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - reportSuiteName
            - ownerFullName
            - modified
            - tags
            - compatibility
            - definition
            - publishingStatus
            - definitionLastModified
            - categories
          enum:
          - reportSuiteName
          - ownerFullName
          - modified
          - tags
          - compatibility
          - definition
          - publishingStatus
          - definitionLastModified
          - categories
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSegmentResponseItem'
        '400':
          description: Invalid input; name, rsid, and definition are all required. Definition must be formatted as a JSON Object.
        '500':
          description: External API error; Segment create or retrieval failed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyticsSegment'
        description: JSON-formatted Object containing key/value pairs for segment creation.
        required: true
  /{globalCompanyId}/segments/validate:
    post:
      tags:
      - Segments
      summary: Create validation for segment
      description: Returns a segment validation for the segment contained in the post body of the report.
      operationId: segments_validateSegment
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: rsid
        in: query
        description: RSID to run the report against
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SegmentCompatibility'
        '400':
          description: Bad JSON input; request not formatted correctly
        '500':
          description: Unexpected error;
      requestBody:
        content:
          application/json:
            schema:
              type: string
        description: Segment definition
        required: true
  /{globalCompanyId}/segments/{id}:
    get:
      tags:
      - Segments
      summary: Retrieve a segment by ID
      description: ''
      operationId: segments_getSegment
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: id
        in: path
        description: The segment ID to retrieve
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale. Valid values include 'en_US', 'fr_FR', 'ja_JP', 'de_DE', 'es_ES', 'ko_KR', 'pt_BR', 'zh_CN', and 'zh_TW'.
        required: false
        schema:
          type: string
          default: en_US
      - name: expansion
        in: query
        description: Comma-delimited list of additional segment metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - reportSuiteName
            - ownerFullName
            - modified
            - tags
            - compatibility
            - definition
            - publishingStatus
            - definitionLastModified
            - categories
          enum:
          - reportSuiteName
          - ownerFullName
          - modified
          - tags
          - compatibility
          - definition
          - publishingStatus
          - definitionLastModified
          - categories
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSegmentResponseItem'
        '403':
          description: Requesting non-shared segments for other users is restricted to admin users
        '500':
          description: External API error; segment retrieval failed
    put:
      tags:
      - Segments
      summary: Update a segment by ID
      description: ''
      operationId: segments_updateSegment
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: id
        in: path
        description: Segment ID to be updated
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale. Valid values include 'en_US', 'fr_FR', 'ja_JP', 'de_DE', 'es_ES', 'ko_KR', 'pt_BR', 'zh_CN', and 'zh_TW'.
        required: false
        schema:
          type: string
          default: en_US
      - name: expansion
        in: query
        description: Comma-delimited list of additional segment metadata fields to include on response.
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - reportSuiteName
            - ownerFullName
            - modified
            - tags
            - compatibility
            - definition
            - publishingStatus
            - definitionLastModified
            - categories
          enum:
          - reportSuiteName
          - ownerFullName
          - modified
          - tags
          - compatibility
          - definition
          - publishingStatus
          - definitionLastModified
          - categories
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSegmentResponseItem'
        '400':
          description: Definition must be formatted as a JSON Object
        '401':
          description: Company mismatch; segment ownership can only be transferred within the same organization
        '403':
          description: User does not have permission to update this segment
        '500':
          description: External API error; Segment update or retrieval failed
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: object
        description: JSON-formatted Object containing key/value pairs to be updated.
    delete:
      tags:
      - Segments
      summary: Delete a segment by ID
      description: ''
      operationId: segments_deleteSegment
      parameters:
      - name: globalCompanyId
        in: path
        description: The Global Company ID for the Adobe Analytics organization
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - name: id
        in: path
        description: The segment ID to be deleted
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale. Valid values include 'en_US', 'fr_FR', 'ja_JP', 'de_DE', 'es_ES', 'ko_KR', 'pt_BR', 'zh_CN', and 'zh_TW'.
        required: false
        schema:
          type: string
          default: en_US
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: string
        '500':
          description: External API error; Segment delete failed
components:
  parameters:
    x-api-key:
      name: x-api-key
      in: header
      description: The API key copied from your AA API client integration. For more information on how to obtain this value, see [Getting started with the Analytics API](https://developer.adobe.com/analytics-apis/docs/2.0/guides/).
      required: true
      schema:
        type: string
    authorization:
      name: Authorization
      in: header
      description: The access token copied from your AA API client integration, prefixed with "Bearer ".
      required: true
      schema:
        type: string
  schemas:
    TaggedComponent:
      type: object
      properties:
        componentType:
          type: string
        componentId:
          type: string
        tags:
          type: array
          items:
            type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int32
          description: the tag id
        name:
          type: string
          description: 'the tag name '
        description:
          type: string
          description: the tag description
        components:
          type: array
          description: the list of components that have been tagged with this tag
          uniqueItems: true
          items:
            $ref: '#/components/schemas/TaggedComponent'
      description: Tag Model
    AnalyticsSegmentDefinition:
      type: object
      properties:
        container:
          type: object
          properties:
            context:
              type: string
            func:
              type: string
            pred:
              type: object
              properties:
                val:
                  type: object
                  properties:
                    description:
                      type: string
                    name:
                      type: string
                    func:
                      type: string
                str:
                  type: string
                func:
                  type: string
        func:
          type: string
        version:
          type: array
          items:
            type: integer
            format: int32
    Owner:
      type: object
      required:
      - id
      properties:
        id:
          type: integer
          format: int32
          description: the login id of the owner
        name:
          type: string
          description: the friendly full login name of the owner, included when the expansion parameter ownerFullName is true
        login:
          type: string
          description: the friendly full login name of the owner, included when the expansion parameter ownerFullName is true
    AnalyticsSegment:
      type: object
      properties:
        name:
          type: string
          description: A name for the segment.
        description:
          type: string
          description: A description of the segment.
        rsid:
          type: string
          description: The report suite id.
        reportSuiteName:
          type: string
          description: The friendly name for the report suite id.
        owner:
          description: The owner of the segment as an Owner object.
          $ref: '#/components/schemas/Owner'
        definition:
          type: object
          description: The segment definition as a JSON object
          $ref: '#/components/schemas/AnalyticsSegmentDefinition'
        compatibility:
          type: object
          description: Analytics products that the segment is compatible with
          $ref: '#/components/schemas/SegmentCompatibility'
        definitionLastModified:
          type: string
          format: date-time
        categories:
          type: array
          items:
            type: string
        siteTitle:
          type: string
          description: A name for the report suite.  This is deprecated and should use the report suite name instead.
        tags:
          type: array
          description: All existing tags associated with the segment.
          items:
            $ref: '#/components/schemas/Tag'
        modified:
          type: string
          format: date-time
        created:
          type: string
          format: date-time
    SegmentCompatibility:
      type: object
      properties:
        valid:
          type: boolean
        message:
          type: string
        validator_version:
          type: string
        supported_products:
          type: array
          items:
            type: string
        supported_schema:
          type: array
          items:
            type: string
        supported_features:
          type: array
          items:
            type: string
    AnalyticsSegmentResponseItem:
      type: object
      properties:
        id:
          type: string
          description: Id of the segment.
        name:
          type: string
          description: A name for the segment.
        description:
          type: string
          description: A description of the segment.
        rsid:
          type: string
          description: The report suite id.
        reportSuiteName:
          type: string
          description: The friendly name for the report suite id.
        owner:
          description: The owner of the segment as an Owner object.
          $ref: '#/components/schemas/Owner'
        definition:
          type: object
          description: The segment definition as a JSON object
          $ref: '#/components/schemas/AnalyticsSegmentDefinition'
        compatibility:
          type: object
          description: Analytics products that the segment is compatible with
          $ref: '#/components/schemas/SegmentCompatibility'
        definitionLastModified:
          type: string
          format: date-time
        categories:
          type: array
          items:
            type: string
        siteTitle:
          type: string
          description: A name for the report suite.  This is deprecated and should use the report suite name instead.
        tags:
          type: array
          description: All existing tags associated with the segment.
          items:
            $ref: '#/components/schemas/Tag'
        modified:
          type: string
          format: date-time
        created:
          type: string
          format: date-time