openapi: 3.1.0
info:
  title: Pendo Engage API
  description: >-
    The Pendo Engage API provides programmatic access to product analytics data
    and in-app guide management. Endpoints cover visitors, accounts, features,
    pages, guides, reports, and metadata used to push and pull product usage
    data and to manage Pendo configuration outside the UI. Authentication uses
    a per-subscription integration key sent in the X-Pendo-Integration-Key
    header.
  version: "1.0"
  contact:
    name: Pendo Engage API
    url: https://engageapi.pendo.io/
servers:
  - url: https://app.pendo.io/api/v1
    description: Pendo US data center
  - url: https://app.eu.pendo.io/api/v1
    description: Pendo EU data center
security:
  - integrationKey: []
tags:
  - name: Visitors
  - name: Accounts
  - name: Features
  - name: Pages
  - name: Guides
  - name: Reports
  - name: Metadata
paths:
  /visitor/{visitorId}:
    parameters:
      - name: visitorId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Visitors]
      summary: Get a visitor
      operationId: getVisitor
      responses:
        '200':
          description: Visitor details.
  /metadata/visitor/custom/value:
    post:
      tags: [Metadata]
      summary: Set custom visitor metadata values
      operationId: setVisitorCustomMetadata
      responses:
        '200':
          description: Metadata updated.
  /account/{accountId}:
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Accounts]
      summary: Get an account
      operationId: getAccount
      responses:
        '200':
          description: Account details.
  /metadata/account/custom/value:
    post:
      tags: [Metadata]
      summary: Set custom account metadata values
      operationId: setAccountCustomMetadata
      responses:
        '200':
          description: Metadata updated.
  /feature:
    get:
      tags: [Features]
      summary: List features
      operationId: listFeatures
      responses:
        '200':
          description: A list of features.
  /feature/{featureId}:
    parameters:
      - name: featureId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Features]
      summary: Get a feature
      operationId: getFeature
      responses:
        '200':
          description: Feature details.
  /page:
    get:
      tags: [Pages]
      summary: List pages
      operationId: listPages
      responses:
        '200':
          description: A list of pages.
  /page/{pageId}:
    parameters:
      - name: pageId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Pages]
      summary: Get a page
      operationId: getPage
      responses:
        '200':
          description: Page details.
  /guide:
    get:
      tags: [Guides]
      summary: List guides
      operationId: listGuides
      responses:
        '200':
          description: A list of guides.
  /guide/{guideId}:
    parameters:
      - name: guideId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Guides]
      summary: Get a guide
      operationId: getGuide
      responses:
        '200':
          description: Guide details.
  /report:
    get:
      tags: [Reports]
      summary: List reports
      operationId: listReports
      responses:
        '200':
          description: A list of reports.
  /report/{reportId}/results.csv:
    parameters:
      - name: reportId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Reports]
      summary: Get report results as CSV
      operationId: getReportResultsCsv
      responses:
        '200':
          description: CSV report results.
          content:
            text/csv: {}
  /aggregation:
    post:
      tags: [Reports]
      summary: Execute an aggregation query
      operationId: runAggregation
      description: >-
        Runs an ad-hoc aggregation pipeline against Pendo data (events, visitor
        history, etc.) and returns the result rows.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Aggregation result rows.
components:
  securitySchemes:
    integrationKey:
      type: apiKey
      in: header
      name: X-Pendo-Integration-Key
      description: Per-subscription Pendo integration key issued from the Pendo UI.