--- title: "Search API | Ceisium Docs" description: "Auth, request fields, response shape, result limits, errors, and examples." canonical: https://ceisium.com/docs/search-api/ --- > For the complete documentation and public content index, see [llms.txt](/llms.txt). This page is the Markdown alternative to the canonical HTML page. ## Start 1. [Quickstart Create a project, crawl it, query the API, and embed search.](https://ceisium.com/docs/) 2. [Search API Auth, request fields, response shape, pagination, errors, and examples.](https://ceisium.com/docs/search-api/) 3. [UI Components Install search UI patterns and wire them to a Ceisium Search project.](https://ceisium.com/docs/ui-components/) 4. [Analytics Read search events, no-result queries, popular queries, and engagement.](https://ceisium.com/docs/analytics/) ## Search quality 1. [Benchmark Results, response times, and methods for our search comparison.](https://ceisium.com/docs/benchmark/) ## Observability 1. [Crawl Logs Track crawl status, page outcomes, failures, retries, and coverage.](https://ceisium.com/docs/crawl-logs/) 2. [Usage Review API requests, crawl volume, indexing usage, and plan limits.](https://ceisium.com/docs/usage/) 1. [Home](https://ceisium.com/) 2. / 3. [Docs](https://ceisium.com/docs/) 4. / 5. Search API Updated Sep 27, 2026 # Search API Auth, request fields, response shape, result limits, errors, and examples. Browse docs ## Start 1. [Quickstart](https://ceisium.com/docs/) 2. [Search API](https://ceisium.com/docs/search-api/) 3. [UI Components](https://ceisium.com/docs/ui-components/) 4. [Analytics](https://ceisium.com/docs/analytics/) ## Search quality 1. [Benchmark](https://ceisium.com/docs/benchmark/) ## Observability 1. [Crawl Logs](https://ceisium.com/docs/crawl-logs/) 2. [Usage](https://ceisium.com/docs/usage/) Use the Search API directly from a website with a Browser/public key, or from a backend with a Server key. ## Endpoint TXT ``` POST https://api.ceisium.com/v1/search ``` ## Choose a key type Key type Use it from Required guardrails Browser/public keys Browser code Exact allowed website origins, optional allowed result URL prefixes, per-IP and total-key rate limits. Server keys A trusted backend Total-key rate limit. Never expose these keys in browser code. Use `CEISIUM_PUBLIC_SEARCH_KEY` for browser integrations and `CEISIUM_SEARCH_KEY` for server integrations. Both key types are search-only and belong to one project. ## Auth Pass a Search API key as a bearer token. TXT ``` Authorization: Bearer $CEISIUM_PUBLIC_SEARCH_KEYContent-Type: application/json ``` For a Browser/public key, Ceisium Search checks the browser-supplied `Origin` against the key’s allowed origins. **Origin is required**: a missing or disallowed origin returns `403`. Enter complete origins such as `https://docs.example.com` or `http://localhost:3000`; Ceisium Search also adds the expected scheme when you enter a bare hostname or localhost during key creation. Origins cannot contain paths. If the key has allowed result URL prefixes, each request must also include a matching `path_prefix`. Origin and path restrictions limit where a public key can be used and what it can return. Keep Server keys private because they do not use browser-origin restrictions. ## Request body Field Type Required Notes `project_id` string yes The project to search. `query` string yes The visitor search query. `top_k` number no Requested result count. Defaults to `10`; accepted range is `1` to `50`. The response is capped to the key’s configured maximum, which defaults to `20`. `path_prefix` string no Limit results to a URL prefix, such as `https://nextjs.org/docs/app`. This includes the App Router root page and its child paths. ## Browser example TS ``` const response = await fetch("https://api.ceisium.com/v1/search", { method: "POST", headers: { Authorization: `Bearer ${CEISIUM_PUBLIC_SEARCH_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ project_id: CEISIUM_PROJECT_ID, query: "How do I add typed JSON-LD to a page component?", top_k: 8, path_prefix: "https://nextjs.org/docs/app", }),}); ``` Do not manually set `Origin`; browsers add it to cross-origin requests. ## Server example SH ``` curl -X POST https://api.ceisium.com/v1/search \ -H "Authorization: Bearer $CEISIUM_SEARCH_KEY" \ -H "Content-Type: application/json" \ -d '{ "project_id": "'$CEISIUM_PROJECT_ID'", "query": "How do I add typed JSON-LD to a page component?", "top_k": 5, "path_prefix": "https://nextjs.org/docs/app" }' ``` ## Per-minute limits New keys start with plan-based defaults. You can edit these values when creating a key; they are defaults, not plan ceilings. Plan Browser searches per IP Total searches per key Starter 60 per IP per minute 100 total per minute Growth 100 per IP per minute 1,000 total per minute Pro 200 per IP per minute 5,000 total per minute Browser/public keys apply both limits. Server keys apply only the total-key limit because many visitors may share the server’s outbound IP. Per-minute limits protect against short traffic bursts; the plan’s monthly search allowance is counted separately. When a request exceeds either applicable per-minute limit, the API returns `429`. A request whose `top_k` is higher than the key’s maximum is capped to the key’s configured maximum rather than rejected. ## Response Render `title`, `snippet`, and `url`. Treat `score` as an internal ranking signal, not visitor-facing copy. ## Errors Status Meaning `401` Missing or invalid API key. `402` Billing is inactive, usage data is stale, or the monthly allowance is exhausted. `403` Project, origin, or result-path access is not allowed for this key. `404` Project not found. `413` Request body is too large. `422` Invalid body, empty query, or `top_k` outside `1` to `50`. `429` A per-IP or total-key per-minute limit was reached. `500` Search backend error. Retry later and check observability. [Previous Quickstart](https://ceisium.com/docs/) [Next UI Components](https://ceisium.com/docs/ui-components/) Copy page Copy page Copy page as Markdown for LLMs [ ![](https://www.google.com/s2/favicons?domain=chatgpt.com&sz=32)Open in ChatGPT ↗ Ask questions about this page ](https://chatgpt.com/?q=Use%20this%20documentation%20page%20as%20context%20and%20help%20me%20answer%20questions%20about%20it%3A%20Search%20API%20https%3A%2F%2Fceisium.com%2Fdocs%2Fsearch-api%2F)[ ![](https://www.google.com/s2/favicons?domain=claude.ai&sz=32)Open in Claude ↗ Ask questions about this page](https://claude.ai/new?q=Use%20this%20documentation%20page%20as%20context%20and%20help%20me%20answer%20questions%20about%20it%3A%20Search%20API%20https%3A%2F%2Fceisium.com%2Fdocs%2Fsearch-api%2F)