openapi: 3.0.1
info:
  title: Coveo Activity Activities Dimensions API - Version 15 API
  description: API for Coveo Platform
  termsOfService: https://www.coveo.com/en/support/terms-agreements
  contact:
    name: Coveo
    url: https://connect.coveo.com/s/discussions
  version: 1.0.0
servers:
- url: https://platform.cloud.coveo.com
  description: Coveo public API endpoint
security:
- oauth2:
  - full
tags:
- name: Dimensions API - Version 15
paths:
  /v15/dimensions/custom:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get All the Custom Dimensions
      operationId: get__v15_dimensions_custom
      parameters:
      - name: includeOnlyParents
        in: query
        description: This will filter out dimensions which are covered by others. Only parent/master dimensions will be output
        schema:
          type: boolean
          default: false
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DimensionResponseV15'
    post:
      tags:
      - Dimensions API - Version 15
      summary: Create a Custom Dimension
      operationId: post__v15_dimensions_custom
      parameters:
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: name
        in: query
        description: The name of the custom dimension. It should start with the 'c_' prefix. If not present, the prefix will be added automatically.
        schema:
          type: string
      - name: event
        in: query
        description: The types of event where this dimension will be added.
        required: true
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
            enum:
            - searches
            - clicks
            - custom_events
      - name: updatePastEvents
        in: query
        description: Whether to update the custom dimension in past events.
        deprecated: true
        schema:
          type: boolean
          default: false
      requestBody:
        description: The custom dimension information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDimensionModelV15'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionResponseV15'
  /v15/dimensions/custom/{apiName}:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get a Custom Dimension
      operationId: get__v15_dimensions_custom_{apiName}
      parameters:
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: apiName
        in: path
        description: Format must be `EVENT.DIMENSION` where EVENT is the event type and DIMENSION is the name of the dimension.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionResponseV15'
    put:
      tags:
      - Dimensions API - Version 15
      summary: Create or Edit a Custom Dimension
      operationId: put__v15_dimensions_custom_{apiName}
      parameters:
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: apiName
        in: path
        description: Format must be `EVENT.DIMENSION` where EVENT is the event type and DIMENSION is the name of the dimension.
        required: true
        schema:
          type: string
      - name: updatePastEvents
        in: query
        description: Whether to update the custom dimension in past events.
        deprecated: true
        schema:
          type: boolean
          default: false
      requestBody:
        description: The custom dimension information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomDimensionModelV15'
        required: true
      responses:
        '200':
          description: The custom dimension has been edited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionResponseV15'
        '201':
          description: The custom dimension has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionResponseV15'
    delete:
      tags:
      - Dimensions API - Version 15
      summary: Delete a Custom Dimension
      operationId: delete__v15_dimensions_custom_{apiName}
      parameters:
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: apiName
        in: path
        description: Format must be `EVENT.DIMENSION` where EVENT is the event type and DIMENSION is the name of the dimension.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No content
  /v15/dimensions/custom/{event}/suggestions:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get a List of Dimensions That Have Data but Are Not Created Yet
      operationId: get__v15_dimensions_custom_{event}_suggestions
      parameters:
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: from
        in: query
        description: The beginning date of the date range. ISO8601 format 'YYYY-MM-DDThh:mm:ss.sssZ'
        schema:
          type: string
      - name: to
        in: query
        description: The end date of the date range. ISO8601 format 'YYYY-MM-DDThh:mm:ss.sssZ'
        schema:
          type: string
      - name: event
        in: path
        description: The type of event for which to look for suggestions.
        required: true
        schema:
          type: string
          enum:
          - searches
          - clicks
          - custom_events
      - name: includeValueSamples
        in: query
        description: Whether value samples should be included in the response.
        schema:
          type: boolean
          default: true
      - name: depth
        in: query
        description: The number of events to look at when getting suggestions. A larger depth means more suggestions but also slower performance.
        schema:
          type: integer
          format: int32
          default: 1000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomDimensionSuggestionsResponseV15'
  /v15/dimensions/custom/monitoring/health:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Health Check for the Custom Dimensions Service
      operationId: get__v15_dimensions_custom_monitoring_health
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
  /v15/dimensions/custom/status:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get the Custom Dimensions Service Status
      operationId: get__v15_dimensions_custom_status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
  /v15/dimensions/custom/{dimension}/values:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get the Values for a Custom Dimension
      operationId: get__v15_dimensions_custom_{dimension}_values
      parameters:
      - name: from
        in: query
        description: The beginning date of the date range. ISO8601 format 'YYYY-MM-DDThh:mm:ss.sssZ'
        required: true
        schema:
          type: string
      - name: to
        in: query
        description: The end date of the date range. ISO8601 format 'YYYY-MM-DDThh:mm:ss.sssZ'
        required: true
        schema:
          type: string
      - name: tz
        in: query
        description: Timezone used for calculations.
        schema:
          type: string
          default: Z
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: dimension
        in: path
        description: The dimensions to fetch.
        required: true
        schema:
          type: string
      - name: f
        in: query
        description: The filter that will be applied to the events dimensions. Multiple filter parameters are joined with the AND operator.
        schema:
          type: array
          items:
            type: string
      - name: p
        in: query
        description: The response's page to access, starting at 1.
        schema:
          type: integer
          format: int32
      - name: n
        in: query
        description: The number of results to include in a page.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionValuesResponseV15'
  /v15/dimensions/{apiName}:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get a Dimension
      operationId: get__v15_dimensions_{apiName}
      parameters:
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: apiName
        in: path
        description: Format must be `EVENT.DIMENSION` where EVENT is the event type and DIMENSION is the name of the dimension.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionResponseV15'
  /v15/dimensions:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get All the Dimensions
      operationId: get__v15_dimensions
      parameters:
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: includeOnlyParents
        in: query
        description: This will filter out dimensions which are covered by others. Only parent/master dimensions will be output
        schema:
          type: boolean
          default: false
      - name: includeCustom
        in: query
        description: Whether to include custom dimensions within the results.
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DimensionResponseV15'
  /v15/dimensions/exportables:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get All the Exportable Dimensions
      operationId: get__v15_dimensions_exportables
      parameters:
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: includeOnlyParents
        in: query
        description: This will filter out dimensions which are covered by others. Only parent/master dimensions will be output
        schema:
          type: boolean
          default: false
      - name: includeCustom
        in: query
        description: Whether to include custom dimensions within the results.
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DimensionResponseV15'
  /v15/dimensions/monitoring/health:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Health Check for the Dimensions Service
      operationId: get__v15_dimensions_monitoring_health
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
  /v15/dimensions/status:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get the Dimensions Service Status
      operationId: get__v15_dimensions_status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
  /v15/dimensions/{dimension}/values:
    get:
      tags:
      - Dimensions API - Version 15
      summary: Get the Values for a Dimension
      operationId: get__v15_dimensions_{dimension}_values
      parameters:
      - name: from
        in: query
        description: The beginning date of the date range. ISO8601 format 'YYYY-MM-DDThh:mm:ss.sssZ'
        required: true
        schema:
          type: string
      - name: to
        in: query
        description: The end date of the date range. ISO8601 format 'YYYY-MM-DDThh:mm:ss.sssZ'
        required: true
        schema:
          type: string
      - name: tz
        in: query
        description: Timezone used for calculations.
        schema:
          type: string
          default: Z
      - name: org
        in: query
        description: The name of the organization (Coveo Cloud V2 only)
        schema:
          type: string
      - name: dimension
        in: path
        description: The dimensions to fetch.
        required: true
        schema:
          type: string
      - name: f
        in: query
        description: The filter that will be applied to the events dimensions. Multiple filter parameters are joined with the AND operator.
        schema:
          type: array
          items:
            type: string
      - name: p
        in: query
        description: The response's page to access, starting at 1.
        schema:
          type: integer
          format: int32
      - name: n
        in: query
        description: The number of results to include in a page.
        schema:
          type: integer
          format: int32
      - name: cached
        in: query
        description: cached
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionValuesResponseV15'
components:
  schemas:
    CustomDimensionSuggestionResponseV15:
      type: object
      properties:
        eventName:
          type: string
          description: The event type of the custom dimension
        apiName:
          type: string
          description: The api name of the custom dimension
        values:
          uniqueItems: true
          type: array
          description: The existing values for the custom dimension
          items:
            type: string
            description: The existing values for the custom dimension
      description: Information regarding the custom dimension
    StatusResponse:
      type: object
      description: Service's status information
    CustomDimensionSuggestionsResponseV15:
      required:
      - suggestions
      type: object
      properties:
        suggestions:
          type: array
          description: Information regarding the custom dimension
          items:
            $ref: '#/components/schemas/CustomDimensionSuggestionResponseV15'
      description: Suggestions of custom dimensions that could be created
    CustomDimensionModelV15:
      required:
      - displayName
      - type
      type: object
      properties:
        type:
          type: string
          description: The type of the dimension
          enum:
          - TEXT
          - NUMBER
          - SHORT
          - BOOLEAN
          - DATE
          - DATETIME
          - TEXT
          - NUMBER
          - SHORT
          - BOOLEAN
          - DATE
          - DATETIME
        displayName:
          type: string
          description: The display name of the dimension. Should be human readable
        path:
          type: array
          description: 'Strings that correspond to the path that must be followed to fetch the desired value of the dimension in the custom_datas map. For example, let''s consider the following custom_datas map: ''{"a":{"b":"c"}}''. To select the value "c", the path would need to contain the elements "a" and "b".'
          items:
            type: string
      description: Additional required information to create a custom dimension
    DimensionValuesResponseV15:
      type: object
      properties:
        values:
          type: array
          description: The values for this dimension
          items:
            type: object
            additionalProperties:
              type: object
              description: The values for this dimension
            description: The values for this dimension
      description: The values for this dimension
    DimensionResponseV15:
      required:
      - apiNames
      - custom
      - displayName
      - eventTypes
      - returnName
      - status
      - type
      type: object
      properties:
        type:
          type: string
          description: The type of the dimension
          enum:
          - TEXT
          - NUMBER
          - SHORT
          - BOOLEAN
          - DATE
          - DATETIME
        displayName:
          type: string
          description: The display name of the dimension
        apiNames:
          uniqueItems: true
          type: array
          description: A collection of possible names to use when querying the statistics service with this dimension
          items:
            type: string
            description: A collection of possible names to use when querying the statistics service with this dimension
        returnName:
          type: string
          description: The name of the dimension when returned by the statistics service
        custom:
          type: boolean
          description: A flag indicating if the dimension is a custom dimension
        availableInVisit:
          type: boolean
          description: Whether the dimension is available in a visit's statistics.
        eventTypes:
          uniqueItems: true
          type: array
          description: Indicates the type of events that this dimension can be attached to.
          items:
            type: string
            description: Indicates the type of events that this dimension can be attached to.
        status:
          type: string
          description: The status of the dimension
          enum:
          - AVAILABLE
          - UPDATING
        path:
          type: array
          description: The path in the custom_datas map corresponding to this dimension. For custom dimensions only.
          items:
            type: string
            description: The path in the custom_datas map corresponding to this dimension. For custom dimensions only.
      description: The details of a dimension
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://platform.cloud.coveo.com/oauth/authorize
          tokenUrl: https://platform.cloud.coveo.com/oauth/token
          scopes:
            full: required