SerpKite Gemini API

openapi: 3.2.0
info:
  title: SerpKite SERP Gemini API
  version: 1.12.4
  description: 'Public search API (api.serpkite.com). Google results as clean JSON or Markdown

    for AI agents, plus a Google Custom Search–compatible endpoint. Official SDKs:

    `serpkite` on npm and PyPI, `github.com/serpkite/serpkite-go`. **Auth:** `Authorization: Bearer skt_live_…`. A bare `Authorization: skt_live_…`

    (no scheme) is also accepted, for MCP hosts that can''t add one. GET requests

    may pass `?api_key=` instead. `/customsearch/v1` also accepts Google''s `?key=`. **Bodies:** every vertical accepts `POST` with a JSON object or `GET` with the

    same parameters in the query string (only `GET /v1/search` is spelled out

    here). Unknown parameters are rejected with 400, and so is a parameter the

    endpoint would ignore (e.g. `time` on `/v1/scholar`, `ll` on `/v1/search`). To run many queries at once,

    use `POST /v1/batches`. **Formats:** `format=json` (default) returns the schemas below. `format=markdown` returns `text/markdown` for every vertical. `format=compact` and `fields=` return a reduced JSON object (same top-level

    keys, fewer item fields, `meta` always kept), so required item fields may be

    absent there. **Responses** share one envelope: `request` (the normalised request),

    `results` (the vertical''s primary list), vertical-specific extras and `meta`. All keys are snake_case. **Credits** are decimal numbers (e.g. `0.5`). Failed, empty and blocked

    responses are refunded. Every billed response carries `X-Credits-Used`,

    `X-Credits-Remaining`, `X-Cost-USD`, `X-Cache` (`HIT`|`MISS`), `X-Latency-Ms`,

    `X-Tokens-Estimate` and `X-Request-Id`. **Errors** share one body: `{"error":{"code","message","request_id"}}`. Upstream failures (`upstream_error`, `upstream_blocked`, `upstream_timeout`)

    are `503` with `Retry-After`, never billed and safe to retry. The API never

    returns `502` or `504`. `429` also carries `Retry-After`: `rate_limited` is

    the per-second limit; `daily_limit_reached` is the free daily limit of an

    account that never bought a pack, which resets at 00:00 UTC (the message

    names the limit and the billing page; buying any pack removes it). `403 account_restricted` means the account''s free use is paused because it

    appears to be one of several accounts run by the same person (same device

    or network, or requests in step with other accounts) or uses a disposable

    email address; buying any pack lifts it. **CORS:** `Access-Control-Allow-Origin: *` without credentials; the `X-*`

    headers above are exposed, so a browser playground can call the API with a key. The keyless `/playground/search` is the exception: it only answers serpkite.com

    and app.serpkite.com (other `Origin`s get 403). Credit table: search/news/images/videos/maps/places/shopping/scholar/patents/

    webpage/customsearch = 1 per page; place details = 1; `num=100` depth bundle = 7; reviews = 1 per 10;

    autocomplete = 0.5; `include_content` = +1 per fetched page;

    batches ×0.5 (from 2026-11-23 a batch depth request is 0.5 per page with

    results, without the bundle cap: `num=100` = 5); cache hit via `max_age` ×0.5. `engine=consensus` (search only) =

    the sum of one page per provider that returned results. **AI** (Claude writes, OpenAI''s Decisions API runs typed checks; a failed

    model step is never billed): an answer (`include_answer` on `/v1/search` and

    `/v1/news`, the model part of `/v1/answer`) = +2 over the result page, +4

    when it read pages (`include_content`, `/v1/answer` depth=standard);

    `/v1/extract` `summary` = +4 and `output_schema` = +4 per page;

    `/v1/research` = lite 30, standard 75, deep 200. Responses that used a

    model carry `meta.llm`. **AI assistants** (`/v1/chatgpt`, `/v1/gemini`, `/v1/copilot`,

    `/v1/ai_mode`, `/v1/brave_ai`): a `prompt` sent to the public assistant

    as a logged-out user; the response is its answer

    (`text`, `markdown`) with the `sources` it cited or listed,

    `search_queries`, `products` and `places` where the assistant shows them,

    and `mentions` for the brands and domains in `track`.'
servers:
- url: https://api.serpkite.com
- url: http://localhost:8080
security:
- bearer: []
tags:
- name: Gemini
paths:
  /v1/gemini:
    post:
      summary: Ask Google Gemini as a logged-out user and get its answer with the sources it…
      operationId: gemini
      description: 'Opens gemini.google.com as a logged-out visitor and sends `prompt`. Most

        answers take 5–30 s; answers that search the web take longer. `country`

        asks as a visitor in that country.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantRequest'
            example:
              prompt: How do heat pumps work in cold climates?
      responses:
        '200':
          $ref: '#/components/responses/AssistantOK'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '402':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Unavailable'
      tags:
      - Gemini
components:
  headers:
    RetryAfter:
      description: Seconds to wait before retrying
      schema:
        type: integer
    CreditsRemaining:
      schema:
        type: number
    TokensEstimate:
      schema:
        type: integer
    LatencyMs:
      schema:
        type: integer
    CreditsUsed:
      schema:
        type: number
    CostUSD:
      schema:
        type: number
    Cache:
      schema:
        type: string
        enum:
        - HIT
        - MISS
  schemas:
    PlacePhoto:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          description: Image URL (at most 1600 px on the long side)
        width:
          type: integer
        height:
          type: integer
        source:
          type: string
          enum:
          - business
          - visitor
          description: Who uploaded it, when Google says (Google shows no contributor names to logged-out visitors)
    Mention:
      type: object
      required:
      - term
      - mentioned
      - cited
      - sources
      - text_position
      properties:
        term:
          type: string
        mentioned:
          type: boolean
          description: 'The answer text names it (a domain: names the domain)'
        cited:
          type: boolean
          description: A cited source matches it
        sources:
          type: array
          items:
            type: integer
          description: Positions of the matching sources
        products:
          type: array
          items:
            type: integer
          description: Positions of the matching products
        text_position:
          type: number
          description: Where the text first names it, 0 (start) to 1 (end); -1 when it doesn't
    AISource:
      type: object
      required:
      - position
      - link
      - domain
      - cited
      properties:
        position:
          type: integer
          description: The number the answer cites it with ([n] in markdown)
        title:
          type: string
        link:
          type: string
        domain:
          type: string
        snippet:
          type: string
        date:
          type: string
        cited:
          type: boolean
          description: 'Cited inline in the answer (false: only listed beside it)'
    TrackList:
      type: array
      maxItems: 20
      items:
        type: string
        maxLength: 100
      description: Brands ("Acme") and domains ("acme.com", subdomains match) to check the answer for; each comes back in `mentions`
    AssistantEcho:
      type: object
      description: The normalised request of an AI assistant endpoint (the path names the assistant, so there is no engine)
      required:
      - endpoint
      - prompt
      properties:
        endpoint:
          type: string
          examples:
          - chatgpt
          - gemini
        prompt:
          type: string
        country:
          type: string
        language:
          type: string
          description: Not on chatgpt
        web_search:
          type: boolean
          description: chatgpt only
        include_html:
          type: boolean
    HoursInterval:
      type: object
      required:
      - open
      - close
      properties:
        open:
          type: string
          pattern: ^[0-2][0-9]:[0-5][0-9]$
          examples:
          - 08:00
        close:
          type: string
          pattern: ^[0-2][0-9]:[0-5][0-9]$
          examples:
          - '22:00'
        next_day:
          type: boolean
          description: The interval closes after midnight, on the next day
    PlaceResult:
      type: object
      required:
      - position
      - title
      properties:
        position:
          type: integer
        title:
          type: string
        address:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        rating:
          type: number
        rating_count:
          type: integer
        price_level:
          type: string
        type:
          type: string
        types:
          type: array
          items:
            type: string
        website:
          type: string
        phone_number:
          type: string
        international_phone_number:
          type: string
          examples:
          - +44 20 7232 3010
        opening_hours:
          type: object
          additionalProperties:
            type: string
          description: 'Hours as the provider displays them, keyed by English weekday (Monday … Sunday), in `language`, e.g. {"Monday": "7:30 am–6 pm", "Sunday": "Closed"}; Yandex Maps: 24-hour times ("08:00–22:00"), "Closed"/"выходной", "Open 24 hours"/"круглосуточно"'
        weekly_hours:
          $ref: '#/components/schemas/WeeklyHours'
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code of the place, upper case (RU, GB)
        timezone:
          type: string
          description: IANA time zone of the place (Europe/Moscow)
        description:
          type: string
          description: Google's short description of the place, or the owner's, when Google shows one; Yandex Maps' summary of the place when it has one
        photos:
          type: array
          description: Photos of the place (/v1/place; up to 10). The URLs are public and can be fetched server-side without cookies
          items:
            $ref: '#/components/schemas/PlacePhoto'
        google_maps_url:
          type: string
          description: The place on Google Maps
        thumbnail_url:
          type: string
        place_id:
          type: string
        cid:
          type: string
        fid:
          type: string
        oid:
          type: string
          description: Yandex Maps organisation id (engine=yandex), for /v1/place
        yandex_maps_url:
          type: string
          description: 'The place on Yandex Maps (engine=yandex): https://yandex.ru/maps/org/<oid>/'
    Meta:
      type: object
      required:
      - request_id
      - credits_used
      - cached
      properties:
        request_id:
          type: string
        credits_used:
          type: number
        engine:
          type: string
          description: The provider that produced the result (`consensus` for a merged engine=consensus answer)
          examples:
          - google
          - brave
          - consensus
          - stub
        route:
          type: array
          description: Provider attempts in order (fresh results only; absent on cache hits). With engine=consensus, every provider started; ones stopped early are `canceled`, ones cut off by the deadline `timeout`
          items:
            $ref: '#/components/schemas/RouteStep'
        cached:
          type: boolean
        cached_at:
          type: string
          format: date-time
        resolved_urls:
          type: boolean
        parse_quality:
          type: string
          enum:
          - ok
          - partial
          - empty
        latency_ms:
          type: integer
        llm:
          $ref: '#/components/schemas/LLMUsage'
        warnings:
          type: array
          items:
            type: string
          description: Non-fatal problems, e.g. an include_answer that failed (and was refunded)
    AIProduct:
      type: object
      required:
      - position
      - title
      properties:
        position:
          type: integer
        title:
          type: string
        brand:
          type: string
        price:
          type: string
          description: As shown
          e.g. "€69.90": null
        extracted_price:
          type: number
        currency:
          type: string
          description: ISO 4217 when the symbol is unambiguous
        rating:
          type: number
        reviews:
          type: integer
        merchant:
          type: string
        link:
          type: string
        image:
          type: string
        description:
          type: string
        sponsored:
          type: boolean
          description: A paid placement (an ad card shown with the answer)
    AssistantResponse:
      type: object
      required:
      - request
      - text
      - markdown
      - sources
      - search_queries
      - products
      - meta
      properties:
        request:
          $ref: '#/components/schemas/AssistantEcho'
        text:
          type: string
          description: The answer as plain text
        markdown:
          type: string
          description: The answer as Markdown, citations as [n](link) matching sources[].position
        html:
          type: string
          description: Only with include_html=true
        model:
          type: string
          description: The model the assistant reports, when it does (e.g. ChatGPT's guest model)
        sources:
          type: array
          items:
            $ref: '#/components/schemas/AISource'
        search_queries:
          type: array
          items:
            type: string
          description: The searches the assistant ran (fan-out) where it shows them
        products:
          type: array
          items:
            $ref: '#/components/schemas/AIProduct'
        places:
          type: array
          items:
            $ref: '#/components/schemas/PlaceResult'
          description: Local businesses the answer showed
        related_questions:
          type: array
          items:
            type: string
        mentions:
          type: array
          items:
            $ref: '#/components/schemas/Mention'
          description: With track only
        meta:
          $ref: '#/components/schemas/Meta'
    HoursIntervals:
      type: array
      items:
        $ref: '#/components/schemas/HoursInterval'
    WeeklyHours:
      type: object
      description: 'Opening hours per weekday, from the provider''s listing, as local times (`timezone`) in 24-hour HH:MM.

        A day that is closed is an empty list; a day open 24 hours is `[{"open": "00:00", "close": "24:00"}]`;

        a day with a break has several intervals. `close` is "24:00" at midnight, and an interval that

        ends after midnight has `next_day: true` (e.g. 17:30–03:00). Days Google doesn''t list are absent;

        Yandex Maps lists all seven or none.

        '
      properties:
        monday:
          $ref: '#/components/schemas/HoursIntervals'
        tuesday:
          $ref: '#/components/schemas/HoursIntervals'
        wednesday:
          $ref: '#/components/schemas/HoursIntervals'
        thursday:
          $ref: '#/components/schemas/HoursIntervals'
        friday:
          $ref: '#/components/schemas/HoursIntervals'
        saturday:
          $ref: '#/components/schemas/HoursIntervals'
        sunday:
          $ref: '#/components/schemas/HoursIntervals'
    RouteStep:
      type: object
      description: One provider attempt behind this answer.
      required:
      - provider
      - outcome
      - ms
      properties:
        provider:
          type: string
          examples:
          - google
          - brave
        outcome:
          type: string
          enum:
          - ok
          - partial
          - empty
          - soft_empty
          - blocked
          - timeout
          - error
          - unsupported
          - bad_param
          - bad_target
          - canceled
        ms:
          type: integer
          description: Duration of the attempt in milliseconds
    AssistantRequest:
      type: object
      required:
      - prompt
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 4000
          description: The message to the assistant
        country:
          type: string
          description: 'Ask from this country (ISO 3166-1 alpha-2): answers, prices and shops follow it'
        language:
          type: string
          description: Interface language (e.g. en, de); the answer follows the prompt's language
        track:
          $ref: '#/components/schemas/TrackList'
        include_html:
          type: boolean
          default: false
          description: Also return the answer page's HTML (`html`)
        format:
          type: string
          enum:
          - json
          - markdown
          - compact
          default: json
        fields:
          type: string
        max_age:
          type: integer
          minimum: 0
          maximum: 2592000
          description: Accept a cached answer up to this many seconds old (half price); answers are cached for at most an hour
    LLMUsage:
      type: object
      description: The model that wrote this response's AI part and the tokens it used
      properties:
        provider:
          type: string
          examples:
          - anthropic
          - openai
        model:
          type: string
          examples:
          - claude-haiku-5-5
          - gpt-6-luna
        input_tokens:
          type: integer
        output_tokens:
          type: integer
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: '403: spend_cap_reached, key_limit_reached, account_restricted, forbidden. 409/422: idempotency_key_reused. 422: target_unavailable (the URL you asked for failed: its site answered 404, its domain doesn''t resolve; resending won''t help), no_pages. 429: rate_limited, daily_limit_reached. 503: upstream_error, upstream_blocked, upstream_timeout, unavailable (the API never sends 502 or 504)'
              examples:
              - unauthorized
              - invalid_request
              - insufficient_credits
              - rate_limited
              - daily_limit_reached
              - spend_cap_reached
              - key_limit_reached
              - account_restricted
              - idempotency_key_reused
              - forbidden
              - not_found
              - upstream_error
              - upstream_blocked
              - upstream_timeout
              - unavailable
              - internal
            message:
              type: string
            request_id:
              type: string
  responses:
    Unavailable:
      description: 'Temporarily unavailable, not billed, safe to retry after `Retry-After`.

        Codes: `upstream_error` (the upstream page couldn''t be fetched or parsed),

        `upstream_blocked` (the upstream is rate limiting us or refused the query), `upstream_timeout`

        (the search took too long), `unavailable` (endpoint or dependency down).

        The API never sends 502 or 504.

        '
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AssistantOK:
      description: OK (text/markdown when format=markdown)
      headers:
        X-Credits-Used:
          $ref: '#/components/headers/CreditsUsed'
        X-Credits-Remaining:
          $ref: '#/components/headers/CreditsRemaining'
        X-Cost-USD:
          $ref: '#/components/headers/CostUSD'
        X-Cache:
          $ref: '#/components/headers/Cache'
        X-Latency-Ms:
          $ref: '#/components/headers/LatencyMs'
        X-Tokens-Estimate:
          $ref: '#/components/headers/TokensEstimate'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AssistantResponse'
        text/markdown:
          schema:
            type: string
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
    oauth:
      type: oauth2
      description: OAuth 2.1 for the remote MCP server only (authorization code + PKCE S256; app-api.serpkite.com is the authorization server).
      flows:
        authorizationCode:
          authorizationUrl: https://app-api.serpkite.com/oauth/authorize
          tokenUrl: https://app-api.serpkite.com/oauth/token
          refreshUrl: https://app-api.serpkite.com/oauth/token
          scopes:
            mcp: Use the SerpKite MCP tools, billed to your account
            offline_access: Stay connected with refresh tokens