---
name: ceisium-search
description: Use Ceisium Search to add and operate website search from public web content. Use when a user needs to crawl a site, index its pages, create a project-scoped Search key, call the Search API, restrict results by URL prefix, inspect crawl outcomes, or integrate search into a website.
license: Proprietary
compatibility: Requires network access to ceisium.com and a Ceisium Search account for authenticated product actions.
metadata:
  author: Ceisium
  version: "1.0"
---

# Ceisium Search

Ceisium Search turns a public website into a project-scoped search index. It crawls allowed pages, extracts useful content, and returns ranked results through an authenticated REST API.

## Capabilities

- Explain how Ceisium Search crawling, indexing, and search work.
- Guide a user through creating a project and adding a website source.
- Help define include and exclude rules for public website content.
- Help create the correct Search key type for a browser or trusted server.
- Build typed calls to `POST https://api.ceisium.com/v1/search`.
- Restrict results with an absolute `path_prefix`.
- Interpret crawl progress, indexed-page counts, Search API errors, and usage limits.
- Find the current Ceisium Search API and product documentation.

## Required inputs

Ask for only the inputs needed for the current task:

- Public website or documentation URL.
- Ceisium Search project ID for API calls.
- Search query.
- Desired result count from 1 to 50.
- Optional absolute result URL prefix.
- Intended caller: browser code or trusted server code.

Never ask a user to paste a private API key into chat. Use an environment-variable placeholder in examples.

## Workflow

1. Read [llms.txt](https://ceisium.com/llms.txt) to find the current resource.
2. For API work, read the [OpenAPI contract](https://ceisium.com/openapi.json) and [Search API guide](https://ceisium.com/docs/search-api/index.md).
3. Confirm whether the integration runs in a browser or on a trusted server.
4. Use a Browser/public Search key only with exact allowed origins. Use a Server Search key only in trusted backend code.
5. Send a JSON request with `project_id`, `query`, optional `top_k`, and optional `path_prefix`.
6. Handle the documented HTTP errors. Do not treat an empty result list as an API failure.
7. Show the result title, snippet, and URL. Treat `score` as an internal ranking signal.

## Search request

```bash
curl https://api.ceisium.com/v1/search \
  -H "Authorization: Bearer $CEISIUM_SEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "prj_example",
    "query": "OpenTelemetry Python instrumentation",
    "top_k": 5,
    "path_prefix": "https://docs.example.com/"
  }'
```

## Constraints

- Ceisium Search is for public website content. Do not propose indexing secrets or private data without a separate approved security design.
- Search requests require a project-scoped bearer key. The health and capabilities endpoints do not require authentication.
- Browser/public keys require an allowed browser origin. Do not manually set the `Origin` header in browser JavaScript.
- Server keys must not appear in client code, logs, screenshots, documentation, or source control.
- A key cannot search another project.
- `top_k` must be an integer from 1 to 50 and can be reduced by the key's configured maximum.
- `path_prefix` must be an absolute URL prefix allowed by the key.
- Preserve real HTTP failures. Do not retry `401`, `402`, `403`, or `422` without correcting the cause.
- Do not claim that Ceisium Search can search a page until the page has been crawled and indexed.

## Resources

- [Developer resources](https://ceisium.com/developers/index.md)
- [OpenAPI 3.1 contract](https://ceisium.com/openapi.json)
- [Search API guide](https://ceisium.com/docs/search-api/index.md)
- [Quickstart](https://ceisium.com/docs/index.md)
- [Usage and limits](https://ceisium.com/docs/usage/index.md)
- [Crawl logs](https://ceisium.com/docs/crawl-logs/index.md)
- [Contact](https://ceisium.com/contact/index.md)