# OpenAPI spec

> The SerpKite SERP API is described by an OpenAPI 3.1 document. Download it to generate typed clients, import the API into Postman, Insomnia or Bruno, or give it to an LLM.

The contract for `api.serpkite.com` is a single OpenAPI 3.1 file. It is the source of truth the API is built from: when an endpoint or field changes, this file changes first.

- **Download:** [https://serpkite.com/openapi/serp-api.yaml](https://serpkite.com/openapi/serp-api.yaml)
- **Format:** OpenAPI 3.1.0, YAML
- **Version:** 1.0.0

```bash
curl -O https://serpkite.com/openapi/serp-api.yaml
```

## What's in it

- **Servers:** `https://api.serpkite.com`.
- **Security scheme:** `bearer` (`Authorization: Bearer skt_live_…`). GET requests may also pass `?api_key=`.
- **Every endpoint:** `/v1/search`, `/v1/images`, `/v1/videos`, `/v1/news`, `/v1/maps`, `/v1/places`, `/v1/reviews`, `/v1/shopping`, `/v1/scholar`, `/v1/patents`, `/v1/autocomplete`, `/v1/lens`, `/v1/webpage`, `/v1/rank`, `POST /v1/batches`, `/v1/batches/{id}`, `/v1/account`, `/v1/status`, `/customsearch/v1`, plus the no-login `/playground/search` demo and the `/v1/mcp` endpoint.
- **Request schemas:** `SearchRequest` (shared by the search verticals), `ReviewsRequest`, `LensRequest`, `WebpageRequest`, `RankRequest`, `BatchCreateRequest`.
- **Response schemas:** one per vertical (`SearchResponse`, `NewsResponse`, `PlacesResponse`…), all sharing the `request` / `results` / `meta` envelope (`RequestEcho`, `Meta`), plus `RankResponse`, `Batch`, `BatchCreateResponse`, `Account`, `Status`, `CSEResponse` and the `Error` shape.
- **Headers:** `X-Credits-Used`, `X-Credits-Remaining`, `X-Cost-USD`, `X-Cache`, `X-Latency-Ms` and `X-Tokens-Estimate` on every billed response.
- **Alternate content types:** `text/markdown` responses for `format: "markdown"`.

The dashboard backend (`app-api.serpkite.com`) is an internal API for the SerpKite dashboard and is not part of the public contract.

## Generate a client

For TypeScript, Python and Go, use the [official SDKs](https://serpkite.com/docs/sdks), which are generated from this spec and hand-polished. For other languages, or if you want your own types, generators produce good clients from the spec.

TypeScript types with [openapi-typescript](https://openapi-ts.dev), used with `openapi-fetch`:

```bash
npx openapi-typescript https://serpkite.com/openapi/serp-api.yaml -o src/serpkite.d.ts
```

Go with [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen):

```bash
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
curl -sO https://serpkite.com/openapi/serp-api.yaml
oapi-codegen -generate types,client -package serpkite serp-api.yaml > serpkite/client.gen.go
```

Python, Java, C#, Ruby, PHP and more with [OpenAPI Generator](https://openapi-generator.tech):

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://serpkite.com/openapi/serp-api.yaml \
  -g python \
  -o ./serpkite-client
```

Some generators struggle with OpenAPI 3.1 `oneOf` unions, such as the job-or-error entries of `BatchCreateResponse` or the engine-or-list `engine` parameter. If one does, keep the generated models and send requests with your own thin wrapper.

## Import into an API client

- **Postman:** **Import → Link**, paste `https://serpkite.com/openapi/serp-api.yaml`. Set the collection's auth to **Bearer Token** with your key.
- **Insomnia:** **Create → Import → From URL**, paste the same URL.
- **Bruno:** **Import Collection → OpenAPI V3 Spec**, choose the downloaded file.

Keep the key in an environment variable of the tool, not in the saved requests you share.

## Use it with an LLM

The spec is compact enough to paste into a model's context when you ask it to write integration code. For the prose docs as well, use [llms.txt](https://serpkite.com/llms.txt) (an index) or [llms-full.txt](https://serpkite.com/llms-full.txt) (every docs page as Markdown), or add `.md` to any docs URL.

## Versioning

The API is at version 1.0.0. Additive changes (new endpoints, new optional parameters, new response fields) ship without a version bump, so parse responses tolerantly and ignore unknown fields. Breaking changes will get a new version and advance notice in the [API changelog](https://serpkite.com/docs/changelog).