Search the web for the Caveman engine on Caveman Code credits

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.

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

Headers

x-caveman-clientstring

caveman-code/<version>. Required in practice: web search is sold to the Caveman Code client only, so without it the credits ledger refuses with 403 cave_code_client_required.

x-caveman-sessionstring

Labels the ledger row with the caller's session; optional.

Request body

querystring required

What to search for: 1 to 400 characters once whitespace runs are folded to single spaces; no control characters. Never logged or stored.

countinteger

The most results to return.

freshness'day' | 'week' | 'month' | 'year'

Only pages from the last day, week, month or year.

domainsstring[]

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

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

provider'brave' | 'perplexity' required

Who answered: Brave LLM Context, or Perplexity Search when Brave failed.

cost_usdnumber 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.

Changes

No recorded changes to this operation across all 1 revision of this API.