Search API

Auth, request fields, response shape, result limits, errors, and examples.

Browse docs

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 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 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://signoz.io/docs/`.

Browser example

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: "OpenTelemetry Python instrumentation",    top_k: 8,    path_prefix: "https://signoz.io/docs/",  }),});

Do not manually set Origin; browsers add it to cross-origin requests.

Server example

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": "OpenTelemetry Python instrumentation",    "top_k": 5,    "path_prefix": "https://signoz.io/docs/"  }'

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.