Convert Experiences Heatmaps API

openapi: 3.2.0
info:
  title: Convert Experiences Heatmaps API
  description: Move your app forward with the Convert API.
  version: 2.0.0
servers:
- url: https://api.convert.com/api/v2
  description: Live API server
- url: https://apidev.convert.com/api/v2
  description: DEV API server
- url: http://apidev.convert.com:5000/api/v2
  description: DEV mocked API server
tags:
- name: Experiences Heatmaps
  description: Endpoints to retrieve heatmap background and overlay images (Convert Signals™). Filters such as device and interaction type are passed in the request body.
paths:
  /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/heatmaps/{heatmap_id}/background:
    post:
      operationId: getExperienceHeatmapBackground
      summary: Get heatmap background image
      description: Retrieves the background image for a specific heatmap and device.
      tags:
      - Experiences Heatmaps
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ExperienceId'
      - $ref: '#/components/parameters/HeatmapId'
      requestBody:
        $ref: '#/components/requestBodies/GetExperienceHeatmapBackgroundRequest'
      responses:
        '200':
          $ref: '#/components/responses/ExperienceHeatmapBackgroundResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/heatmaps/{heatmap_id}/overlay:
    post:
      operationId: getExperienceHeatmapOverlay
      summary: Get heatmap overlay (interaction) image
      description: Retrieves the overlay image for a specific heatmap, device, and interaction type.
      tags:
      - Experiences Heatmaps
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ExperienceId'
      - $ref: '#/components/parameters/HeatmapId'
      requestBody:
        $ref: '#/components/requestBodies/GetExperienceHeatmapOverlayRequest'
      responses:
        '200':
          $ref: '#/components/responses/ExperienceHeatmapOverlayResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    ExperienceHeatmapOverlayResponseData:
      type: object
      description: Response for POST heatmap overlay by heatmap id.
      properties:
        data:
          type: object
          properties:
            heatmap_id:
              type: string
            device:
              $ref: '#/components/schemas/HeatmapDevices'
            interaction:
              $ref: '#/components/schemas/HeatmapInteractions'
            overlay:
              type: string
              format: byte
              nullable: true
              description: Base64-encoded overlay image. Null when available is false.
    ErrorData:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        fields:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
    GetExperienceHeatmapOverlayRequestData:
      type: object
      description: Optional filters for the heatmap overlay (interaction) image.
      properties:
        device:
          $ref: '#/components/schemas/HeatmapDevices'
        interaction:
          $ref: '#/components/schemas/HeatmapInteractions'
    HeatmapDevices:
      type: string
      enum:
      - desktop
      - tablet
      - mobile
      default: desktop
      description: Device type for the heatmap image.
    HeatmapInteractions:
      type: string
      enum:
      - click
      - scroll
      - move
      default: click
      description: Interaction type for the heatmap overlay.
    GetExperienceHeatmapBackgroundRequestData:
      type: object
      description: Optional filters for the heatmap background image.
      properties:
        device:
          $ref: '#/components/schemas/HeatmapDevices'
    ExperienceHeatmapBackgroundResponseData:
      type: object
      description: Response for POST heatmap background by heatmap id.
      properties:
        data:
          type: object
          properties:
            heatmap_id:
              type: string
            device:
              $ref: '#/components/schemas/HeatmapDevices'
            background:
              type: string
              format: byte
              nullable: true
              description: Base64-encoded background image. Null when available is false.
  parameters:
    HeatmapId:
      name: heatmap_id
      in: path
      required: true
      description: ID of the heatmap.
      schema:
        type: string
    ExperienceId:
      name: experience_id
      in: path
      required: true
      description: ID of the experience
      schema:
        type: integer
    ProjectId:
      name: project_id
      in: path
      required: true
      description: ID of the project to be retrieved
      schema:
        type: integer
    AccountId:
      name: account_id
      in: path
      required: true
      description: ID of the account that owns the retrieved/saved data
      schema:
        type: integer
  requestBodies:
    GetExperienceHeatmapBackgroundRequest:
      description: Optional filters for the heatmap background image (e.g. device). Passed in body for extensibility.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetExperienceHeatmapBackgroundRequestData'
      required: false
    GetExperienceHeatmapOverlayRequest:
      description: Optional filters for the heatmap overlay image (e.g. device, interaction type). Passed in body for extensibility.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetExperienceHeatmapOverlayRequestData'
      required: false
  responses:
    ExperienceHeatmapBackgroundResponse:
      description: Heatmap background image for the given heatmap id and device.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExperienceHeatmapBackgroundResponseData'
    ExperienceHeatmapOverlayResponse:
      description: Heatmap overlay (interaction) image for the given heatmap id, device, and interaction type.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExperienceHeatmapOverlayResponseData'
    ErrorResponse:
      description: 'Indicates an error occurred while processing the request. The `code` provides an HTTP status code, `message` offers a human-readable explanation or an array of validation errors, and `fields` (if present) specifies which input fields were problematic.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorData'
  securitySchemes:
    requestSigning:
      type: apiKey
      x-name-applicationId: Convert-Application-ID
      x-name-expire: Expire
      name: Authorization
      in: header
      description: 'See **[API Key Authentication](#tag/API-KEY-Authentication)** for more information.

        '
    secretKey:
      type: http
      scheme: bearer
      description: 'See **[API Key Authentication](#tag/API-KEY-Authentication)** for more information.

        '
    cookieAuthentication:
      type: apiKey
      in: cookie
      name: sid
      description: Cookie authentication is used against Convert's own IdentityProvider  or third party identity providers and is described more in the "[Cookie Authentication](#tag/Cookie-Authentication)" section
x-tagGroups:
- name: Client Authentication
  tags:
  - API KEY Authentication
  - Cookie Authentication
  - OAuth Authorization
- name: Common Parameters
  tags:
  - Optional Fields
  - Expandable Fields
- name: Requests
  tags:
  - User
  - Accounts
  - AI content
  - Collaborators
  - API Keys
  - Projects
  - SDK Keys
  - Experiences
  - Experience Variations
  - Experience Sections
  - Section Versions
  - Version Changes
  - Experiences Reports
  - Experiences Heatmaps
  - Goals
  - Hypotheses
  - Knowledge Bases
  - Observations
  - Locations
  - Audiences
  - Domains
  - Cdn Images
  - Files
  - Tags
  - Features
  - Visitor Insights
  - Visitors Data
  - Visitor Data Placeholders
  - OAuth