Birdeye Search AI API

openapi: 3.2.0
info:
  title: Birdeye Search AI API
  version: '1.0'
  description: 'Operations tagged Search AI across 2 of this provider''s published API definitions: birdeye-birdeye-api-openapi.yml, birdeye-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.birdeye.com
  description: Production
- url: https://api.birdeye.com/resources
tags:
- name: Search AI
  description: Search AI provides a comprehensive view of your business performance across AI-powered search platforms, including data accuracy, sentiment analysis, citations, brand ranking, and overall visibility.
paths:
  /v1/listing/searchAi/account-setup:
    get:
      summary: Get Search AI Configuration
      operationId: get-search-ai-configuration
      tags:
      - Search AI
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 89
                  message: Rate limit exceeded
      security:
      - apiKey: []
    servers:
    - url: https://api.birdeye.com
      description: Production
  /v1/listing/searchAi/available-runs:
    get:
      summary: Get Search AI Available Runs
      operationId: get-search-ai-available-runs
      tags:
      - Search AI
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 89
                  message: Rate limit exceeded
      security:
      - apiKey: []
    servers:
    - url: https://api.birdeye.com
      description: Production
  /v1/listing/searchAi/public/citations:
    post:
      summary: Get Search AI Citations
      operationId: get-search-ai-citations
      tags:
      - Search AI
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 89
                  message: Rate limit exceeded
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                businessNumbers:
                  type: string
                aiModel:
                  type: string
                theme:
                  type: string
                pageNo:
                  type: string
                pageSize:
                  type: string
                startDate:
                  type: string
                endDate:
                  type: string
                viewReportType:
                  type: string
      security:
      - apiKey: []
    servers:
    - url: https://api.birdeye.com
      description: Production
  /v1/listing/searchAi/public/business:
    post:
      summary: Get Search AI Businesses
      operationId: get-search-ai-businesses
      tags:
      - Search AI
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 89
                  message: Rate limit exceeded
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                businessNumbers:
                  type: string
                aiModel:
                  type: string
                theme:
                  type: string
                pageNo:
                  type: string
                pageSize:
                  type: string
                startDate:
                  type: string
                endDate:
                  type: string
                viewReportType:
                  type: string
      security:
      - apiKey: []
    servers:
    - url: https://api.birdeye.com
      description: Production
  /v1/listing/searchAi/public/aio-details?page-size=100&start-index=0:
    post:
      summary: Get Accuracy Report
      operationId: get-accuracy-report
      tags:
      - Search AI
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 89
                  message: Rate limit exceeded
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                businessNumbers:
                  type: string
                aiModels:
                  type: string
                startDate:
                  type: string
                endDate:
                  type: string
      security:
      - apiKey: []
    servers:
    - url: https://api.birdeye.com
      description: Production
  /v1/listing/searchAi/public/swot-details?page-size=100&start-index=0:
    post:
      summary: Get Sentiment Report
      operationId: get-sentiment-report
      tags:
      - Search AI
      parameters: []
      responses:
        '200':
          description: HTTP 200 response
          content:
            application/json:
              schema:
                type: object
                example:
                  code: 89
                  message: Rate limit exceeded
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: http://json-schema.org/draft-07/schema#
              type: object
              properties:
                businessNumbers:
                  type: string
                aiModels:
                  type: string
                startDate:
                  type: string
                endDate:
                  type: string
                viewReportType:
                  type: string
      security:
      - apiKey: []
    servers:
    - url: https://api.birdeye.com
      description: Production
  /v1/listing/searchAi/public/account-setup:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  frequency:
                    type: string
                  quota:
                    type: number
                  billingType:
                    type: string
                  themes:
                    type: array
                    items:
                      type: object
                      properties:
                        theme:
                          type: string
                        prompts:
                          type: array
                          items:
                            type: string
                      required:
                      - theme
                      - prompts
                example:
                  frequency: Monthly
                  quota: 1200
                  billingType: CREDIT_SYSTEM
                  themes:
                  - theme: dental implants
                    prompts:
                    - Find dental clinics near me that specialize in affordable dental implants and offer consultations.
                    - Search for providers offering full mouth dental implants or All-on-4 solutions in my area.
                    - Locate dental offices that provide transparent pricing for dental implants and flexible financing options.
                  - theme: teeth whitening
                    prompts:
                    - Find dental clinics near me offering professional teeth whitening services.
                    - Who provides the best in-office teeth whitening treatments in my area?
                    - Local dentists with advanced teeth whitening options and kits for purchase.
                  - theme: dental crowns
                    prompts:
                    - Find dental clinics near me that specialize in dental crown procedures.
                    - Where can I get affordable zirconia dental crowns from reputable dentists?
                    - Locate dental offices offering same-day dental crown services and consultations.
                  - theme: tooth extractions
                    prompts:
                    - Find dental clinics near me that offer professional tooth extraction services, including same-day tooth extraction and implant placement.
                    - Search for dentists specializing in wisdom tooth extraction and post-extraction care in my area.
                    - Locate private dental practices offering affordable tooth extraction with transparent pricing and quick appointments.
                  - theme: dental bridges
                    prompts:
                    - Find dental clinics near me that offer dental bridges and provide detailed pricing information.
                    - Looking for experienced dentists specializing in dental bridge procedures and consultations.
                    - Best dental practices for dental bridge installation and aftercare services in my area.
              examples:
                response:
                  value:
                    frequency: Monthly
                    quota: 1200
                    billingType: CREDIT_SYSTEM
                    themes:
                    - theme: dental implants
                      prompts:
                      - Find dental clinics near me that specialize in affordable dental implants and offer consultations.
                      - Search for providers offering full mouth dental implants or All-on-4 solutions in my area.
                      - Locate dental offices that provide transparent pricing for dental implants and flexible financing options.
                    - theme: teeth whitening
                      prompts:
                      - Find dental clinics near me offering professional teeth whitening services.
                      - Who provides the best in-office teeth whitening treatments in my area?
                      - Local dentists with advanced teeth whitening options and kits for purchase.
                    - theme: dental crowns
                      prompts:
                      - Find dental clinics near me that specialize in dental crown procedures.
                      - Where can I get affordable zirconia dental crowns from reputable dentists?
                      - Locate dental offices offering same-day dental crown services and consultations.
                    - theme: tooth extractions
                      prompts:
                      - Find dental clinics near me that offer professional tooth extraction services, including same-day tooth extraction and implant placement.
                      - Search for dentists specializing in wisdom tooth extraction and post-extraction care in my area.
                      - Locate private dental practices offering affordable tooth extraction with transparent pricing and quick appointments.
                    - theme: dental bridges
                      prompts:
                      - Find dental clinics near me that offer dental bridges and provide detailed pricing information.
                      - Looking for experienced dentists specializing in dental bridge procedures and consultations.
                      - Best dental practices for dental bridge installation and aftercare services in my area.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/1161Model'
              examples:
                response:
                  value:
                    code: 1161
                    message: Invalid API key
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/89Model'
              examples:
                response:
                  value:
                    code: 89
                    message: Rate limit exceeded
      summary: Get Search AI Configuration
      operationId: getSearchAiConfiguration
      description: Retrieves the Search AI configuration for the specified business.
      tags:
      - Search AI
      parameters:
      - name: Accept
        in: header
        description: e.g. application/json
        required: false
        example: application/json
        schema:
          type: string
          default: application/json
      - name: x-api-key
        in: header
        description: e.g. [Required] Partner specific API key provided by Birdeye for data exchange.
        required: false
        example: '[Required] Partner specific API key provided by Birdeye for data exchange.'
        schema:
          type: string
      - name: x-business-number
        in: header
        description: e.g. - Long Business Number
        required: false
        example: '- Long Business Number'
        schema:
          type: string
    servers:
    - url: https://api.birdeye.com/resources
  /v1/listing/searchAi/public/available-runs:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  availableRuns:
                    type: array
                    items:
                      type: object
                      properties:
                        runDate:
                          type: string
                        themes:
                          type: array
                          items:
                            type: string
                      required:
                      - runDate
                      - themes
                example:
                  availableRuns:
                  - runDate: 15-MAR-2026
                    themes:
                    - dental implants
                  - runDate: 14-MAR-2026
                    themes:
                    - dental implants
                    - teeth whitening
                    - dental bridges
                    - dental crowns
                    - tooth extractions
                  - runDate: 13-MAR-2026
                    themes:
                    - dental implants
                    - teeth whitening
                    - dental bridges
                    - dental crowns
                    - tooth extractions
                  - runDate: 13-FEB-2026
                    themes:
                    - dental implants
                    - teeth whitening
                    - dental bridges
                    - dental crowns
                    - tooth extractions
                  - runDate: 13-JAN-2026
                    themes:
                    - dental implants
                    - teeth whitening
                    - dental bridges
                    - dental crowns
                    - tooth extractions
                  - runDate: 30-DEC-2025
                    themes:
                    - dental implants
                    - teeth whitening
                    - dental bridges
                    - dental crowns
                    - tooth extractions
                  - runDate: 18-NOV-2025
                    themes:
                    - dental implants
                    - teeth whitening
                    - dental bridges
                    - dental crowns
                    - tooth extractions
              examples:
                response:
                  value:
                    availableRuns:
                    - runDate: 15-MAR-2026
                      themes:
                      - dental implants
                    - runDate: 14-MAR-2026
                      themes:
                      - dental implants
                      - teeth whitening
                      - dental bridges
                      - dental crowns
                      - tooth extractions
                    - runDate: 13-MAR-2026
                      themes:
                      - dental implants
                      - teeth whitening
                      - dental bridges
                      - dental crowns
                      - tooth extractions
                    - runDate: 13-FEB-2026
                      themes:
                      - dental implants
                      - teeth whitening
                      - dental bridges
                      - dental crowns
                      - tooth extractions
                    - runDate: 13-JAN-2026
                      themes:
                      - dental implants
                      - teeth whitening
                      - dental bridges
                      - dental crowns
                      - tooth extractions
                    - runDate: 30-DEC-2025
                      themes:
                      - dental implants
                      - teeth whitening
                      - dental bridges
                      - dental crowns
                      - tooth extractions
                    - runDate: 18-NOV-2025
                      themes:
                      - dental implants
                      - teeth whitening
                      - dental bridges
                      - dental crowns
                      - tooth extractions
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/1161Model'
              examples:
                response:
                  value:
                    code: 1161
                    message: Invalid API key
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/89Model'
              examples:
                response:
                  value:
                    code: 89
                    message: Rate limit exceeded
      summary: Get Search AI Available Runs
      operationId: getSearchAiAvailableRuns
      description: Retrieves the Search AI available runs for the specified business.
      tags:
      - Search AI
      parameters:
      - name: Accept
        in: header
        description: e.g. application/json
        required: false
        example: application/json
        schema:
          type: string
          default: application/json
      - name: x-api-key
        in: header
        description: e.g. [Required] Partner specific API key provided by Birdeye for data exchange.
        required: false
        example: '[Required] Partner specific API key provided by Birdeye for data exchange.'
        schema:
          type: string
      - name: x-business-number
        in: header
        description: e.g. [Required] User associated businessNumber
        required: false
        example: '[Required] User associated businessNumber'
        schema:
          type: string
    servers:
    - url: https://api.birdeye.com/resources
components:
  schemas:
    Apiary_getSentimentReport_Request:
      type: object
      properties:
        businessNumbers:
          type: string
          description: Comma-separated list of business numbers to retrieve the report for.
        aiModels:
          type: string
          description: Comma-separated list of AI models to include in the report. Possible values are [**`CHATGPT`**, **`GEMINI`**, **`PERPLEXITY`**]
        startDate:
          type: string
          description: 'Start date for the report range (format: **`yyyy-MM-dd`**).'
        endDate:
          type: string
          description: 'End date for the report range (format: **`yyyy-MM-dd`**).'
        viewReportType:
          type: string
          description: 'Defines the level at which the report is generated. Allowed values: **`LOCATION_LEVEL`**, **`ACCOUNT_LEVEL`**'
        startDate - Start date for the report range (format:
          description: 'Start date for the report range (format: **`yyyy-MM-dd`**).'
        endDate - End date for the report range (format:
          description: 'End date for the report range (format: **`yyyy-MM-dd`**).'
        viewReportType - Defines the level at which the report is generated. Allowed values:
          description: 'Defines the level at which the report is generated. Allowed values: **`LOCATION_LEVEL`**, **`ACCOUNT_LEVEL`**'
      example:
        businessNumbers:
        - 177337970010644
        - 177337970029743
        aiModels:
        - CHATGPT
        - GEMINI
        - PERPLEXITY
        startDate: 2026-03-01
        endDate: 2026-03-31
        viewReportType: LOCATION_LEVEL
    Apiary_getSearchAiBusinesses_Request:
      type: object
      properties:
        businessNumbers:
          type: string
          description: Comma-separated list of business numbers to retrieve the report for.
        aiModel:
          type: string
          description: Possible values are [**`CHATGPT`**, **`GEMINI`**, **`PERPLEXITY`**]
        theme:
          type: string
          description: Specifies the theme or category used to filter the report data.
        pageNo:
          type: string
          description: Specifies the page number for paginated results. Defaults to 1.
        pageSize:
          type: string
          description: Defines the number of records to be returned per page. Defaults to 25.
        startDate:
          type: string
          description: 'Start date for the report range (format: **`mm/dd/yyyy`**).'
        endDate:
          type: string
          description: 'End date for the report range (format: **`mm/dd/yyyy`**).'
        viewReportType:
          type: string
          description: 'Defines the level at which the report is generated. Allowed values: **`LOCATION_LEVEL`**, **`ACCOUNT_LEVEL`**'
        startDate - Start date for the report range (format:
          description: 'Start date for the report range (format: **`mm/dd/yyyy`**).'
        endDate - End date for the report range (format:
          description: 'End date for the report range (format: **`mm/dd/yyyy`**).'
        viewReportType - Defines the level at which the report is generated. Allowed values:
          description: 'Defines the level at which the report is generated. Allowed values: **`LOCATION_LEVEL`**, **`ACCOUNT_LEVEL`**'
      example:
        businessNumbers:
        - 67348934989
        - 327349434334
        - 278237892323
        aiModel: CHATGPT
        theme: Dental implants
        pageNo: 1
        pageSize: 25
        startDate: 03/01/2026
        endDate: 03/31/2026
        viewReportType: LOCATION_LEVEL
    Apiary_getAccuracyReport_Request:
      type: object
      properties:
        businessNumbers:
          type: string
          description: Comma-separated list of business numbers to retrieve the report for.
        aiModels:
          type: string
          description: Comma-separated list of AI models to include in the report. Possible values are [**`CHATGPT`**, **`GEMINI`**, **`PERPLEXITY`**]
        startDate:
          type: string
          description: 'Start date for the report range (format: **`yyyy-MM-dd`**).'
        endDate:
          type: string
          description: 'End date for the report range (format: **`yyyy-MM-dd`**).'
        startDate - Start date for the report range (format:
          description: 'Start date for the report range (format: **`yyyy-MM-dd`**).'
        endDate - End date for the report range (format:
          description: 'End date for the report range (format: **`yyyy-MM-dd`**).'
      example:
        businessNumbers:
        - 177337970010644
        - 177337970029743
        aiModels:
        - CHATGPT
        - GEMINI
        - PERPLEXITY
        startDate: 2025-12-01
        endDate: 2025-12-31
    1161Model:
      type: object
      properties:
        code:
          type: number
        message:
          type: string
      example:
        code: 1161
        message: Invalid API key
    89Model:
      type: object
      properties:
        code:
          type: number
        message:
          type: string
      example:
        code: 89
        message: Rate limit exceeded
  requestBodies:
    Get_Search_AI_CitationsBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Apiary_getSearchAiBusinesses_Request'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Partner specific API key provided by Birdeye for data exchange.
x-refined-from:
- birdeye-birdeye-api-openapi.yml
- birdeye-openapi-original.yml