SerpKite Answer API

openapi: 3.2.0
info:
  title: SerpKite SERP Answer 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: Answer
paths:
  /v1/answer:
    post:
      summary: A cited answer grounded on live Google results, written by Claude (fast = 1 + 2…
      operationId: answer
      description: 'Runs the query on Google, then Claude (Haiku by default) writes a concise answer

        that cites the numbered `results` with `[n]` markers. `depth=fast` answers from

        the result page (snippets, answer box, knowledge panel); `depth=standard`

        (default) also reads the top `num_sources` pages and answers from their

        query-ranked passages. Sources are untrusted: instructions inside pages are

        ignored.


        **Billing:** the search part is priced like `/v1/search` with `include_content`

        (1 credit + 1 per page read, cache rules as usual); the model adds 2 credits at

        `fast` and 4 when it read pages (`standard`; 2 if no page could be read).

        `meta.credits` splits the two. When the model fails the answer part is refunded

        (`503 ai_unavailable`); a search that returned nothing to answer from is answered

        with `answer: null`, a warning, and no model charge.


        **Structured output:** with `output_schema` (a JSON Schema, at most 16 KB) the

        answer is a JSON value in `output` (and `answer` is null). Can''t be combined

        with `stream`.


        **Streaming:** `stream: true` returns `text/event-stream` with these events, in

        order: `results` (`{request, results}`), `delta` (`{text}`, repeated), then

        `done` (`{answer, citations, meta}`) or `error` (`{error}`). Billing headers on a

        stream carry the search part only; the final `meta` has the total.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnswerRequest'
            example:
              q: what is retrieval-augmented generation
              depth: standard
              num_sources: 3
      responses:
        '200':
          description: OK (`text/event-stream` when `stream` is true)
          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/AnswerResponse'
              example:
                request:
                  endpoint: answer
                  engine: google
                  q: what is retrieval-augmented generation
                  country: us
                  language: en
                  num: 10
                  page: 1
                  autocorrect: true
                  device: desktop
                  include_content: 3
                  depth: standard
                  num_sources: 3
                answer: Retrieval-augmented generation (RAG) grounds a language model's answer in documents retrieved at query time [1], which reduces hallucinations and keeps answers current [2].
                citations:
                - index: 1
                  title: Retrieval-augmented generation
                  link: https://en.wikipedia.org/wiki/Retrieval-augmented_generation
                  domain: en.wikipedia.org
                - index: 2
                  title: What is RAG?
                  link: https://www.ibm.com/think/topics/retrieval-augmented-generation
                  domain: ibm.com
                results:
                - index: 1
                  title: Retrieval-augmented generation
                  link: https://en.wikipedia.org/wiki/Retrieval-augmented_generation
                  domain: en.wikipedia.org
                - index: 2
                  title: What is RAG?
                  link: https://www.ibm.com/think/topics/retrieval-augmented-generation
                  domain: ibm.com
                meta:
                  request_id: req_01J9
                  credits_used: 6
                  credits:
                    search: 4
                    answer: 2
                  cached: false
                  engine: google
                  latency_ms: 4410
                  llm:
                    provider: anthropic
                    model: claude-haiku-5-5
                    input_tokens: 3120
                    output_tokens: 88
            text/event-stream:
              schema:
                type: string
                description: 'Server-Sent Events. Each event is `event: <name>\ndata: <JSON>\n\n`:

                  `results` → AnswerStreamResults, `delta` → AnswerStreamDelta,

                  `done` → AnswerStreamDone, `error` → Error.

                  '
              example: 'event: results

                data: {"request":{"endpoint":"answer","q":"what is retrieval-augmented generation"},"results":[{"index":1,"title":"Retrieval-augmented generation","link":"https://en.wikipedia.org/wiki/Retrieval-augmented_generation","domain":"en.wikipedia.org"}]}


                event: delta

                data: {"text":"Retrieval-augmented generation grounds "}


                event: done

                data: {"answer":"Retrieval-augmented generation grounds a model''s answer in documents retrieved at query time [1].","citations":[{"index":1,"title":"Retrieval-augmented generation","link":"https://en.wikipedia.org/wiki/Retrieval-augmented_generation","domain":"en.wikipedia.org"}],"meta":{"request_id":"req_01J9","credits_used":3,"cached":false}}

                '
        '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:
      - Answer
components:
  schemas:
    DomainList:
      description: 'Domains as an array or a comma-separated string, at most 20: a host (`example.com`, subdomains match), a host with a path prefix (`github.com/org`) or a TLD (`.gov`).'
      oneOf:
      - type: string
        examples:
        - github.com,en.wikipedia.org
      - type: array
        maxItems: 20
        items:
          type: string
        examples:
        - - github.com/serpkite
          - .gov
    AnswerResponse:
      type: object
      required:
      - request
      - answer
      - citations
      - results
      - meta
      properties:
        request:
          $ref: '#/components/schemas/RequestEcho'
        answer:
          type:
          - string
          - 'null'
          description: Markdown with `[n]` citation markers. Null with output_schema, or when there was nothing to answer from
        output:
          description: 'output_schema only: the JSON value matching the schema'
        citations:
          type: array
          items:
            $ref: '#/components/schemas/Citation'
          description: The sources the answer cites, in first-cited order
        results:
          type: array
          items:
            $ref: '#/components/schemas/AnswerSource'
        meta:
          $ref: '#/components/schemas/AnswerMeta'
    AnswerMeta:
      allOf:
      - $ref: '#/components/schemas/Meta'
      - type: object
        properties:
          credits:
            type: object
            description: '`credits_used` split into the search and the model part'
            properties:
              search:
                type: number
              answer:
                type: number
    AnswerRequest:
      type: object
      required:
      - q
      properties:
        q:
          type: string
          minLength: 1
          maxLength: 2048
        depth:
          type: string
          enum:
          - fast
          - standard
          default: standard
          description: '`fast` answers from the result page (1 + 2 credits); `standard` also reads the top `num_sources` pages (1 + 1 per page + 4 credits)'
        num_sources:
          type: integer
          minimum: 1
          maximum: 5
          default: 3
          description: Pages read (depth=standard only)
        stream:
          type: boolean
          default: false
          description: Send Server-Sent Events (`results`, `delta`…, `done` | `error`) instead of one JSON body
        output_schema:
          type: object
          additionalProperties: true
          description: A JSON Schema (at most 16 KB). The answer becomes a JSON value in `output`. Not with stream
        country:
          type: string
          default: us
        language:
          type: string
          default: en
        location:
          type: string
        uule:
          type: string
        time:
          type: string
          enum:
          - hour
          - day
          - week
          - month
          - year
        tbs:
          type: string
        device:
          type: string
          enum:
          - desktop
          - mobile
          default: desktop
        safe:
          type: string
          enum:
          - active
          - 'off'
          default: 'off'
        autocorrect:
          type: boolean
          default: true
        max_age:
          type: integer
          minimum: 0
          description: Accept a cached search up to this many seconds old
        engine:
          $ref: '#/components/schemas/EngineParam'
        include_domains:
          $ref: '#/components/schemas/DomainList'
        exclude_domains:
          $ref: '#/components/schemas/DomainList'
        boost_domains:
          $ref: '#/components/schemas/DomainList'
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
    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)
    Citation:
      type: object
      required:
      - index
      - title
      - link
      properties:
        index:
          type: integer
          description: The `[n]` marker used in the text (1-based source number)
        title:
          type: string
        link:
          type: string
        domain:
          type: string
    Provider:
      type: string
      description: A search provider (docs/providers). Which verticals each serves depends on the deployment.
      enum:
      - google
      - brave
      - bing
      - yahoo
      - duckduckgo
      - mojeek
      - wikipedia
      - yandex
    AnswerSource:
      type: object
      description: A result the answer may cite, numbered as in the prompt (`[index]`)
      required:
      - index
      - title
      - link
      properties:
        index:
          type: integer
        title:
          type: string
        link:
          type: string
        domain:
          type: string
        date:
          type: string
          description: Publish date (ISO 8601 when known, else as shown)
    EngineParam:
      description: 'Which search providers may answer. `google` (the default) is Google only; Google requests are retried internally before failing. `auto` allows falling back to other enabled providers, in route order, when Google is blocked or times out. A single other provider (`brave`) or a list (`["google","brave"]`, or `google,brave` in a query string) restricts the request to those providers. `meta.engine` always names the provider that answered and credits follow that provider''s price. A key with "Allow fallback to other search engines" on treats a request without `engine` as `auto`. `consensus` (`/v1/search` only; 400 elsewhere, and it can''t be combined with other names) queries several independent search indexes in parallel (at most one Bing-backed provider, so Yahoo or DuckDuckGo never count as agreeing with Bing), merges the results by URL and ranks them by how many providers returned each one. Each result lists its `sources`; `meta.engine` is `consensus` and `meta.route` lists every provider attempt. Up to three providers answer: a provider that fails or comes back empty hands its turn to the next one in the route. It stops once `num` unique results are in hand or after a few seconds, and costs the sum of one page at each provider that returned results (providers that failed, came back empty or were never started are free). `yandex` serves `/v1/search` from Yandex web search (no `time` filter or `safe: active`: a request naming it gets a 400 with them) and `/v1/maps`, `/v1/places` and `/v1/place` from Yandex Maps, where the deployment enables it (otherwise a 503 `unavailable`, not charged); with `auto` it is the last fallback there.'
      oneOf:
      - type: string
        default: google
        examples:
        - google
        - auto
        - consensus
        - brave
        - google,brave
      - type: array
        items:
          $ref: '#/components/schemas/Provider'
        minItems: 1
    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
    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
    RequestEcho:
      type: object
      description: The normalised request that produced this response (defaults filled in)
      required:
      - endpoint
      - engine
      additionalProperties: true
      properties:
        endpoint:
          type: string
          examples:
          - search
          - news
          - webpage
          - chatgpt
        engine:
          description: The engine policy as asked (google, auto, one provider or a list)
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        q:
          type: string
        url:
          type: string
        country:
          type: string
        language:
          type: string
        location:
          type: string
        num:
          type: integer
        page:
          type: integer
        device:
          type: string
        autocorrect:
          type: boolean
        tbs:
          type: string
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        safe:
          type: string
        place_id:
          type: string
        cid:
          type: string
        fid:
          type: string
        oid:
          type: string
        sort:
          type: string
        include_content:
          type: integer
        format:
          type: string
        include_domains:
          type: array
          items:
            type: string
        exclude_domains:
          type: array
          items:
            type: string
        boost_domains:
          type: array
          items:
            type: string
        highlights:
          type: boolean
        include_answer:
          type: boolean
        prompt:
          type: string
          description: AI assistant endpoints
        web_search:
          type: boolean
          description: /v1/chatgpt
        include_html:
          type: boolean
  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
  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'
    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