SerpKite Map API

openapi: 3.2.0
info:
  title: SerpKite SERP Map 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: Map
paths:
  /v1/map:
    post:
      summary: The URLs of a site, from robots.txt sitemaps and the start page's links…
      operationId: map
      description: 'Reads the sitemaps listed in robots.txt (or `/sitemap.xml`), following sitemap

        indexes; XML, gzip, RSS/Atom and plain-text sitemaps are understood. URLs are

        cleaned (fragment and tracking parameters such as `utm_*`, `gclid` and `fbclid`

        dropped), kept on the site, filtered by `include_paths` / `exclude_paths` and

        de-duplicated (`www.`, scheme and trailing slash folded). `search` ranks the URLs

        by their path words and titles (BM25) and drops the ones that don''t match. Takes

        at most about 30 seconds.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MapRequest'
            example:
              url: https://docs.example.com/
              search: install guide
              limit: 50
      responses:
        '200':
          $ref: '#/components/responses/MapOK'
        '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:
      - Map
components:
  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'
    MapOK:
      description: OK
      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/MapResponse'
          example:
            request:
              endpoint: map
              url: https://docs.example.com/
              limit: 50
              sitemap: include
              include_subdomains: false
              search: install guide
            results:
            - url: https://docs.example.com/install
              lastmod: '2026-09-01'
              source: sitemap
            - url: https://docs.example.com/guide
              title: Guide
              source: page
            meta:
              request_id: req_01J9
              credits_used: 1
              latency_ms: 840
              count: 2
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    LatencyMs:
      schema:
        type: integer
    CreditsUsed:
      schema:
        type: number
    RetryAfter:
      description: Seconds to wait before retrying
      schema:
        type: integer
    CreditsRemaining:
      schema:
        type: number
    CostUSD:
      schema:
        type: number
    Cache:
      schema:
        type: string
        enum:
        - HIT
        - MISS
    TokensEstimate:
      schema:
        type: integer
  schemas:
    MapResponse:
      type: object
      required:
      - request
      - results
      - meta
      properties:
        request:
          type: object
          additionalProperties: true
          properties:
            endpoint:
              type: string
              const: map
            url:
              type: string
            search:
              type: string
            limit:
              type: integer
            sitemap:
              type: string
            include_subdomains:
              type: boolean
            include_paths:
              type: array
              items:
                type: string
            exclude_paths:
              type: array
              items:
                type: string
            ignore_query_parameters:
              type: boolean
        results:
          type: array
          items:
            $ref: '#/components/schemas/MapURL'
        meta:
          type: object
          required:
          - request_id
          - credits_used
          - count
          properties:
            request_id:
              type: string
            credits_used:
              type: number
            latency_ms:
              type: integer
            count:
              type: integer
    MapURL:
      type: object
      required:
      - url
      - source
      properties:
        url:
          type: string
        title:
          type: string
        lastmod:
          type: string
          description: The sitemap's lastmod, as written
        source:
          type: string
          enum:
          - sitemap
          - page
    MapRequest:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: The site (any page of it; sitemaps are read from its origin)
        search:
          type: string
          maxLength: 512
          description: Keep only URLs relevant to these words, most relevant first. When the sitemap lists fewer than 50 URLs, up to 8 of the start page's links are read too, one level deeper
        limit:
          type: integer
          minimum: 1
          maximum: 5000
          default: 100
        include_subdomains:
          type: boolean
          default: false
        include_paths:
          type: array
          items:
            type: string
          maxItems: 20
          description: Regular expressions matched against the URL path; keep only URLs matching one
        exclude_paths:
          type: array
          items:
            type: string
          maxItems: 20
          description: Regular expressions matched against the URL path; drop URLs matching one
        ignore_query_parameters:
          type: boolean
          default: false
          description: Treat URLs that differ only in their query string as one (the first one found is kept)
        sitemap:
          type: string
          enum:
          - include
          - only
          - skip
          default: include
          description: '`include` sitemaps and the start page''s links, `only` sitemaps, `skip` sitemaps (links only)'
    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
  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