---
title: "Search the web for the Caveman engine on Caveman Code credits"
method: POST
path: "/v1/code/search"
---

# Search the web for the Caveman engine on Caveman Code credits

`POST /v1/code/search`

## Request

- Base URL: `https://gateway.caveman.so`
- URL: `https://gateway.caveman.so/v1/code/search`
- Auth: API key in header `x-cave-api-key`

Web search for Caveman Code, paid from the organization's Caveman Code credits on the same meter as model tokens, at the provider's list price with no margin. Needs a Caveman Code credits key (POST /api/v1/code/credits/keys) and, for plan usage, x-caveman-client: caveman-code/<version>. Brave LLM Context answers first; Perplexity Search answers when Brave fails and is configured. Each provider attempt reserves its price before the call, settles when the provider answers and is released at zero when it does not. The project's request guardrails screen the query and the domains first (a block refuses them; a mask may rewrite the query but never a domain) and its hard budgets hold each attempt's price. There is no idempotency key: every call is a new search with its own x-cave-request-id, so a retried request runs and is charged again; retry only after an answer says nothing ran (cave_code_search_unavailable, a credits or rate refusal, a 4xx). Nothing is cached or stored. Hosted Cloud only: a customer install has no credits keys.

## Headers

- `x-caveman-client` string
- `x-caveman-session` string

## Request body

- CodeSearchRequest
  - `query` string, required: What to search for: 1 to 400 characters once whitespace runs are folded to single spaces; no control characters. Never logged or stored.
  - `count` integer: The most results to return.
  - `freshness` 'day' | 'week' | 'month' | 'year': Only pages from the last day, week, month or year.
  - `domains` string[]: Only results from these host names or their subdomains (docs.python.org: no scheme, path, port or address; punycode for international names). Case and a trailing dot are ignored; repeats are dropped.

## Response `200`

The search results, normalised across providers. Cache-Control: no-store.

- CodeSearchResponse
  - `results` object[], required: Pages in the provider's relevance order, each once, at most count; empty when nothing relevant was found (still charged: the provider ran).
    - `url` string, uri, required: An absolute http or https URL.
    - `title` string, required: The page title, or its host name when the provider gave none; at most 512 bytes.
    - `date` string, date: Publication date (YYYY-MM-DD) when the provider knows it.
    - `excerpts` string[], required: Text the provider extracted for the query, at most 4 KiB each; structured data (tables, code) arrives as compact JSON text. May be empty.
  - `provider` 'brave' | 'perplexity', required: Who answered: Brave LLM Context, or Perplexity Search when Brave failed.
  - `cost_usd` number, required: What this search cost on the organization's credits: the answering provider's list price per request (0.005), at cost. A search no provider answered costs nothing.

## Other responses

- `400`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `401`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `402`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `403`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `413`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `429`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `503`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `4XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `5XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.

---

[API](https://skmtc.dev/caveman/apis/caveman-cloud-api.md) - [All operations](https://skmtc.dev/caveman/apis/caveman-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/caveman/apis/caveman-cloud-api/revisions/508312d01cfc?raw)