BusinessMCP Visibility API

openapi: 3.2.0
info:
  title: BusinessMCP Hub Visibility API
  version: 1.0.0
  description: One BusinessMCP API key for company data, IP intelligence, website checks and MCP trust tools. Every call is prepaid and priced in US dollars, paid from the account balance, which is added in any whole-dollar amount from $10 to $5,000; a dollar paid is a dollar of balance and nothing is invoiced afterwards. Send an Idempotency-Key header to make a retry free. The same tools are available over MCP at https://businessmcp.com/api/hub/mcp.
servers:
- url: https://businessmcp.com/api/hub/v1
security:
- bearer: []
tags:
- name: Visibility
paths:
  /tools/fp.ai.visibility_probe/call:
    post:
      operationId: call_fp_ai_visibility_probe
      summary: AI visibility probe
      description: 'Ask Google AI Overviews, Gemini, Perplexity, ChatGPT or Claude one unbranded question, with live web search on, and get back for each engine: whether it answered, whether the answer was grounded in a search, whether the brand (and up to five competitors) was mentioned and at what position, the sources it cited with your own domain flagged, and an excerpt. One sample per engine, priced per engine; an engine that returns nothing is refunded. Repeat over days to measure a trend.


        Pricing: $0.10 per item, charged only for results found.'
      tags:
      - Visibility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/fp_ai_visibility_probe'
            example:
              prompt: best website visitor identification tools for b2b
              brand:
                name: BusinessMCP
                domain: businessmcp.com
              engines:
              - google_ai_overview
              - gemini
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    const: true
                  data: {}
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - ok
                - data
                - meta
                example:
                  ok: true
                  data:
                    prompt: best website visitor identification tools for b2b
                    brand:
                      name: BusinessMCP
                      domain: businessmcp.com
                      terms:
                      - BusinessMCP
                      - businessmcp.com
                    engines:
                    - engine: gemini
                      label: Gemini
                      answered: true
                      grounded: true
                      model: gemini-2.5-flash
                      brand:
                        mentioned: true
                        mentions: 1
                        position: 3
                        sentiment: neutral
                      competitors: []
                      citations:
                      - url: https://example.com/best-visitor-id-tools
                        domain: example.com
                        title: Best visitor identification tools
                        is_own: false
                      own_paths_cited: []
                      answer_excerpt: Popular options include …
                    summary:
                      engines_requested: 2
                      engines_answered: 2
                      engines_grounded: 2
                      engines_mentioning_brand: 1
                      mentioned_rate:
                        hits: 1
                        samples: 2
                        rate: 0.5
                        ciLow: 0.095
                        ciHigh: 0.905
                      competitors_mentioned: []
                      cited_domains:
                      - domain: example.com
                        citations: 1
                        share: 1
                        is_own: false
                    note: One sample per engine …
                  meta:
                    request_id: b1f0…
                    tool: example
                    cost_usd: $0.02
                    replayed: false
        '400':
          description: Invalid input (not charged)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '402':
          description: Balance too low, or a key spend limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '503':
          description: Upstream or billing unavailable (refunded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ai-visibility/probe:
    post:
      operationId: fp_ai_visibility_probe
      summary: AI visibility probe
      description: 'Ask Google AI Overviews, Gemini, Perplexity, ChatGPT or Claude one unbranded question, with live web search on, and get back for each engine: whether it answered, whether the answer was grounded in a search, whether the brand (and up to five competitors) was mentioned and at what position, the sources it cited with your own domain flagged, and an excerpt. One sample per engine, priced per engine; an engine that returns nothing is refunded. Repeat over days to measure a trend.


        Pricing: $0.10 per item, charged only for results found.'
      tags:
      - Visibility
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    const: true
                  data: {}
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                - ok
                - data
                - meta
                example:
                  ok: true
                  data:
                    prompt: best website visitor identification tools for b2b
                    brand:
                      name: BusinessMCP
                      domain: businessmcp.com
                      terms:
                      - BusinessMCP
                      - businessmcp.com
                    engines:
                    - engine: gemini
                      label: Gemini
                      answered: true
                      grounded: true
                      model: gemini-2.5-flash
                      brand:
                        mentioned: true
                        mentions: 1
                        position: 3
                        sentiment: neutral
                      competitors: []
                      citations:
                      - url: https://example.com/best-visitor-id-tools
                        domain: example.com
                        title: Best visitor identification tools
                        is_own: false
                      own_paths_cited: []
                      answer_excerpt: Popular options include …
                    summary:
                      engines_requested: 2
                      engines_answered: 2
                      engines_grounded: 2
                      engines_mentioning_brand: 1
                      mentioned_rate:
                        hits: 1
                        samples: 2
                        rate: 0.5
                        ciLow: 0.095
                        ciHigh: 0.905
                      competitors_mentioned: []
                      cited_domains:
                      - domain: example.com
                        citations: 1
                        share: 1
                        is_own: false
                    note: One sample per engine …
                  meta:
                    request_id: b1f0…
                    tool: example
                    cost_usd: $0.02
                    replayed: false
        '400':
          description: Invalid input (not charged)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
        '402':
          description: Balance too low, or a key spend limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '503':
          description: Upstream or billing unavailable (refunded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/fp_ai_visibility_probe'
            example:
              prompt: best website visitor identification tools for b2b
              brand:
                name: BusinessMCP
                domain: businessmcp.com
              engines:
              - google_ai_overview
              - gemini
components:
  schemas:
    Error:
      type: object
      properties:
        ok:
          const: false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - not_permitted
              - quota_exceeded
              - plan_required
              - not_found
              - invalid_input
              - upstream_failed
              - backend_unavailable
              - unavailable
              - internal
            message:
              type: string
            hint:
              type: string
            retryable:
              type: boolean
            upgrade_url:
              type: string
            details:
              type: object
          required:
          - code
          - message
          - retryable
      required:
      - ok
      - error
    Meta:
      type: object
      properties:
        request_id:
          type: string
        tool:
          type: string
        provider:
          type: string
          enum:
          - first_party
          - vendor
          - publisher
        trust_tier:
          type: string
        cost_usd:
          type: string
          description: What this call cost, e.g. "$0.02".
        trial_usd:
          type: string
          description: The part of the cost paid from promotional balance (always $0 for accounts opened after 2026-10-21).
        paid_usd:
          type: string
          description: The part of the cost the purchased balance paid.
        replayed:
          type: boolean
        balance_usd:
          type: string
          description: Purchased balance left after the call.
        trial_left_usd:
          type: string
          description: Promotional balance left after the call, when any.
      required:
      - request_id
      - tool
      - cost_usd
      - replayed
    fp_ai_visibility_probe:
      type: object
      properties:
        prompt:
          type: string
          minLength: 8
          maxLength: 300
          description: The question a buyer would ask an AI assistant. Must not name the brand (that measures recall, not recommendation).
        brand:
          type: object
          properties:
            name:
              type: string
              minLength: 2
              maxLength: 80
            domain:
              type: string
              minLength: 3
              maxLength: 253
            terms:
              description: Extra aliases to detect, e.g. a product name.
              maxItems: 6
              type: array
              items:
                type: string
                minLength: 3
                maxLength: 60
          required:
          - name
          additionalProperties: false
        competitors:
          maxItems: 5
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                minLength: 2
                maxLength: 80
              domain:
                type: string
                minLength: 3
                maxLength: 253
            required:
            - name
            additionalProperties: false
        engines:
          description: Default google_ai_overview, gemini. Priced per engine.
          minItems: 1
          maxItems: 5
          type: array
          items:
            type: string
            enum:
            - google_ai_overview
            - gemini
            - perplexity
            - chatgpt
            - claude
      required:
      - prompt
      - brand
      additionalProperties: false
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: A BusinessMCP API key (mcph_…).