openapi: 3.1.0
info:
  title: Hotjar REST Authentication Surveys API
  description: The Hotjar REST API provides programmatic access to Hotjar data and functionality. It allows developers to export survey responses, list surveys, automate user lookup and deletion requests, and integrate Hotjar data into external tools and workflows. The API uses OAuth client credentials authentication, returns JSON responses, supports cursor-based pagination, and is rate limited to 3000 requests per minute. It is available on Observe and Ask Scale plans.
  version: '1.0'
  contact:
    name: Hotjar Support
    url: https://help.hotjar.com
  termsOfService: https://www.hotjar.com/legal/policies/terms-of-service/
servers:
- url: https://api.hotjar.io/v1
  description: Hotjar Production API Server
security:
- bearerAuth: []
tags:
- name: Surveys
  description: Endpoints for listing surveys and retrieving survey details for a specific site.
paths:
  /sites/{site_id}/surveys:
    get:
      operationId: listSurveys
      summary: List surveys for a site
      description: Returns a paginated list of surveys for a specific site. Supports cursor-based pagination and optionally includes question details in the response. The site_id can be found in the Sites and Organizations page in your Hotjar account.
      tags:
      - Surveys
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/WithQuestions'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successfully retrieved list of surveys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyListResponse'
        '401':
          description: Missing or invalid authorization header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions for the requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Site not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sites/{site_id}/surveys/{survey_id}:
    get:
      operationId: getSurvey
      summary: Get a specific survey
      description: Returns the details of a specific survey for a site, including its questions, configuration, and status.
      tags:
      - Surveys
      parameters:
      - $ref: '#/components/parameters/SiteId'
      - $ref: '#/components/parameters/SurveyId'
      responses:
        '200':
          description: Successfully retrieved survey details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Survey'
        '401':
          description: Missing or invalid authorization header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions for the requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Survey or site not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    SiteId:
      name: site_id
      in: path
      required: true
      description: The unique identifier for the site. Can be found in the Sites and Organizations page under the respective organization.
      schema:
        type: integer
    Cursor:
      name: cursor
      in: query
      required: false
      description: The cursor value for fetching the next page of results. Obtained from the next_cursor field in a previous response.
      schema:
        type: string
    WithQuestions:
      name: with_questions
      in: query
      required: false
      description: Flag indicating whether question information should be included in the response. Defaults to false.
      schema:
        type: boolean
        default: false
    SurveyId:
      name: survey_id
      in: path
      required: true
      description: The unique identifier for the survey.
      schema:
        type: integer
    Limit:
      name: limit
      in: query
      required: false
      description: The number of items to return per page. Maximum value is 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
  schemas:
    SurveyQuestion:
      type: object
      description: A question within a Hotjar survey, including its type, text, and available answer options.
      properties:
        id:
          type: integer
          description: The unique identifier for the question.
        text:
          type: string
          description: The text content of the question displayed to respondents.
        type:
          type: string
          description: The type of question, such as long-text, short-text, rating, multiple-choice, or nps.
        is_required:
          type: boolean
          description: Whether the question requires an answer before submission.
        choices:
          type: array
          nullable: true
          description: The list of answer choices for multiple-choice questions. Null for open-ended question types.
          items:
            type: string
        labels:
          type: object
          nullable: true
          description: Labels for rating or scale questions. Null for other question types.
        image_url:
          type: string
          nullable: true
          description: URL of an image attached to the question. Null if no image is attached.
    SurveyListResponse:
      type: object
      description: A paginated list of surveys with cursor-based pagination support.
      properties:
        results:
          type: array
          description: The list of surveys returned in this page.
          items:
            $ref: '#/components/schemas/Survey'
        next_cursor:
          type: string
          nullable: true
          description: The cursor value to use for fetching the next page. Null when there are no more results.
    Error:
      type: object
      description: An error response returned by the API when a request fails.
      properties:
        error:
          type: string
          description: The error type or code.
        message:
          type: string
          description: A human-readable description of the error.
    Survey:
      type: object
      description: A Hotjar survey with its configuration, status, and optional question details.
      properties:
        id:
          type: integer
          description: The unique identifier for the survey.
        name:
          type: string
          description: The name of the survey.
        type:
          type: string
          description: The type of survey, such as popover, fullscreen, or external link.
        is_enabled:
          type: boolean
          description: Whether the survey is currently active and collecting responses.
        created_time:
          type: string
          format: date-time
          description: The ISO 8601 timestamp when the survey was created.
        url:
          type: string
          description: The URL path to the survey resource in the API.
        responses_url:
          type: string
          description: The URL path to retrieve the survey responses.
        sentiment_analysis_enabled:
          type: boolean
          description: Whether sentiment analysis is enabled for this survey.
        questions:
          type: array
          description: The list of questions in the survey. Only included when with_questions parameter is set to true.
          items:
            $ref: '#/components/schemas/SurveyQuestion'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from the OAuth token endpoint using client credentials grant.
externalDocs:
  description: Hotjar API Reference
  url: https://help.hotjar.com/hc/en-us/articles/36820005914001-Hotjar-API-Reference