openapi: 3.1.0
info:
  title: Gainsight REST API
  description: >-
    The Gainsight REST API allows developers to integrate customer success data,
    automate workflows, and build custom applications on top of the Gainsight
    platform. Provides access to core Gainsight objects and operations.
  version: '1.0'
  contact:
    name: Gainsight Support
    url: https://support.gainsight.com
    email: support@gainsight.com
  termsOfService: https://www.gainsight.com/terms-of-service/
externalDocs:
  description: Gainsight API Documentation
  url: https://support.gainsight.com/PX/API_for_Developers
servers:
  - url: https://api.gainsight.com
    description: Gainsight Production API
tags:
  - name: Companies
    description: Manage company records
  - name: People
    description: Manage person records
  - name: Reports
    description: Run reports and retrieve analytics data
security:
  - apiKey: []
paths:
  /v1/companies:
    get:
      operationId: listCompanies
      summary: Gainsight List companies
      description: Retrieve a list of company records from Gainsight.
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/pageNumber'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: List of companies returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items:
                          $ref: '#/components/schemas/Company'
                      totalCount:
                        type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCompany
      summary: Gainsight Create a company
      description: Create a new company record in Gainsight.
      tags:
        - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyInput'
      responses:
        '200':
          description: Company created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/companies/{companyId}:
    get:
      operationId: getCompany
      summary: Gainsight Get a company
      description: Retrieve a specific company record by ID.
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/companyId'
      responses:
        '200':
          description: Company details returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Company'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCompany
      summary: Gainsight Update a company
      description: Update an existing company record.
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/companyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyInput'
      responses:
        '200':
          description: Company updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCompany
      summary: Gainsight Delete a company
      description: Delete a company record by ID.
      tags:
        - Companies
      parameters:
        - $ref: '#/components/parameters/companyId'
      responses:
        '200':
          description: Company deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/people:
    get:
      operationId: listPeople
      summary: Gainsight List people
      description: Retrieve a list of person records from Gainsight.
      tags:
        - People
      parameters:
        - $ref: '#/components/parameters/pageNumber'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          description: List of people returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items:
                          $ref: '#/components/schemas/Person'
                      totalCount:
                        type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/reports:
    post:
      operationId: runReport
      summary: Gainsight Run a report
      description: Execute a report query against Gainsight data.
      tags:
        - Reports
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reportId:
                  type: string
                  description: ID of the report to execute
                filters:
                  type: object
                  description: Optional filters to apply
      responses:
        '200':
          description: Report data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        items:
                          type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: accessKey
      in: header
      description: Gainsight REST API access key
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      description: Unique identifier of the company
      schema:
        type: string
    pageNumber:
      name: pageNumber
      in: query
      description: Page number for pagination
      schema:
        type: integer
        default: 0
    pageSize:
      name: pageSize
      in: query
      description: Number of records per page
      schema:
        type: integer
        default: 25
        maximum: 100
  responses:
    Unauthorized:
      description: Authentication failed or access key is missing
    BadRequest:
      description: Invalid request body or parameters
    NotFound:
      description: The requested resource was not found
  schemas:
    ApiResponse:
      type: object
      properties:
        result:
          type: boolean
          description: Whether the operation was successful
        errorCode:
          type: string
          description: Error code if the operation failed
        errorDesc:
          type: string
          description: Error description if the operation failed
        requestId:
          type: string
          description: Unique ID for the request
    Company:
      type: object
      properties:
        Gsid:
          type: string
          description: Gainsight unique identifier
        Name:
          type: string
          description: Company name
        Industry:
          type: string
          description: Industry classification
        ARR:
          type: number
          description: Annual recurring revenue
        LifecycleStage:
          type: string
          description: Current lifecycle stage
        Status:
          type: string
          description: Company status
        CSMName:
          type: string
          description: Customer success manager name
        Employees:
          type: integer
          description: Number of employees
        OriginalContractDate:
          type: string
          format: date
          description: Original contract start date
        RenewalDate:
          type: string
          format: date
          description: Next renewal date
        CreatedDate:
          type: string
          format: date-time
          description: Record creation timestamp
        ModifiedDate:
          type: string
          format: date-time
          description: Record last modified timestamp
    CompanyInput:
      type: object
      required:
        - Name
      properties:
        Name:
          type: string
          description: Company name
        Industry:
          type: string
          description: Industry classification
        ARR:
          type: number
          description: Annual recurring revenue
        LifecycleStage:
          type: string
          description: Current lifecycle stage
        Status:
          type: string
          description: Company status
        Employees:
          type: integer
          description: Number of employees
        RenewalDate:
          type: string
          format: date
          description: Next renewal date
    Person:
      type: object
      properties:
        Gsid:
          type: string
          description: Gainsight unique identifier
        FirstName:
          type: string
          description: First name
        LastName:
          type: string
          description: Last name
        Email:
          type: string
          format: email
          description: Email address
        CompanyId:
          type: string
          description: Associated company ID
        Role:
          type: string
          description: Role or title
        Location:
          type: string
          description: Location
        CreatedDate:
          type: string
          format: date-time
          description: Record creation timestamp
        ModifiedDate:
          type: string
          format: date-time
          description: Record last modified timestamp