Set up Search

A working setup needs three things: published content, the correct index connection and a usable search interface on your website.

1. Select the destination

Open your Project, choose the intended environment and enable Search if it is not attached yet. In a new environment, create your first index, such as Documentation; it becomes the environment’s Default index. Select an existing index or create another, such as Blog. A new index starts empty.

Check the index name before importing, publishing or copying connection details. A preview environment and Production have separate content and credentials. See Indices and environments.

2. Bring in your content

Choose the route that matches the source:

• Crawl website for public pages with readable HTML. Verify ownership of the origin and choose paths and extraction settings; see Crawler.
• Import JSON for a prepared SiteOS content snapshot; see Content and indexing.
• Migrate from Algolia for an accessible index or a records export; see Migrate from Algolia.
• Set up Search with AI when your agent should extract repository content or prepare a custom source.

Review titles, URLs, searchable text and the added/changed/removed counts before publication. A full replacement must contain everything you intend to keep in this index, including its other sources.

Wait for publication to succeed in Activity. Merely uploading or accepting an import does not mean visitors can search it yet.

3. Try real queries

In Playground, search for a known page title, a phrase from its body and a likely misspelling. Open result URLs and verify any section anchors.

If a page is missing from Content, fix the source first. If it is present but ranks poorly, use Relevance to compare a draft with the current results. Choose a few useful articles in Suggestions for visitors who have not typed yet.

4. Connect your website

Open Installation and choose Copy prompt for your agent, or use Set up Search with AI in the header. Allow your website in Settings → Website search, or create a query key for a server proxy in Settings → Server queries. Adapt the search interface to your existing framework and design system, using this index’s delivery details. Follow Website connection for browser delivery, server proxies and credentials.

On the real website, open search, submit a known query and follow a result. Check keyboard navigation, the empty-query suggestions and no-result and unavailable states. A successful Playground query alone does not verify the website integration.

5. Check visitor reporting

New indices start with independent Search analytics collection and 30-day retention. You can instead require analytics consent. Event recording must be installed in the website in either mode. The client reads the collection setting from the index with prepareAnalytics(), so a later change applies to updated clients without code changes. Integrations written before 12 October 2026 must be updated: remove analyticsMode and call prepareAnalytics(), because SiteOS rejects event receipts without a collection mode.

Perform a website search, open a result and inspect Last activity and the report. Playground and installation checks are excluded. Waiting for events in Installation means no event has arrived yet; it does not mean search is disconnected. See Search analytics for collection modes and metric definitions.