Algolia

Algolia is a hosted search API that returns results in milliseconds, with ready-made UI libraries for React, Vue and JavaScript. Agility manages and publishes your content. Algolia helps your visitors find it.

This guide builds on Indexing Agility Content for Search. Read that first. It covers the webhook, signature verification, re-fetching from the Fetch API, deletes and the full reindex, which are the same for every provider. This guide adds the Algolia-specific parts.

Following the previous version of this guide? It used the v4 algoliasearch client, which Algolia stopped supporting on 14 August 2026, and it didn't verify webhook signatures. See Upgrading from the previous guide.

Before you start

• An Algolia account and application (sign up). The Free plan is enough to build and test with. If you host on Vercel, the Algolia integration on the Vercel Marketplace creates the application and adds the keys to your project for you.
• From Settings > API Keys in the Algolia dashboard: your Application ID, your Search API key, and a Write API key. Create a key with only the addObject, deleteObject and settings permissions for your webhook. Don't use the Admin key.
• An Agility webhook with secure delivery on, set up as described in the indexing guide.

npm install algoliasearch react-instantsearch react-instantsearch-nextjs

# .env.local
ALGOLIA_APP_ID=...
ALGOLIA_WRITE_API_KEY=...                 # server only: webhook + reindex
ALGOLIA_INDEX=agility_content
NEXT_PUBLIC_ALGOLIA_APP_ID=...            # the same Application ID, exposed to the browser
NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY=...    # the Search API key — safe in the browser

Configure the index

Run this once (and again whenever you change it). It tells Algolia which attributes to search, in what order of importance, and which ones you'll filter on:

// scripts/configure-algolia.ts
import { algoliasearch } from "algoliasearch"

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_WRITE_API_KEY!)

await client.setSettings({
  indexName: process.env.ALGOLIA_INDEX ?? "agility_content",
  indexSettings: {
    searchableAttributes: ["title", "description", "body"], // earlier = more important
    attributesForFaceting: ["filterOnly(locale)", "kind", "referenceName"],
    attributesToSnippet: ["body:30"],
    customRanking: ["desc(updatedAt)"], // on a tie, prefer newer content
  },
})

For more than one locale, consider one index per locale (agility_content_en-us) so you can set language-specific settings such as queryLanguages and indexLanguages. Otherwise, filter on locale as shown below.

Write to the index

This is the searchIndex object the webhook route and the reindex script import:

// lib/search/provider.ts
import { algoliasearch } from "algoliasearch"
import type { SearchRecord } from "./types"

const client = algoliasearch(process.env.ALGOLIA_APP_ID!, process.env.ALGOLIA_WRITE_API_KEY!)
const indexName = process.env.ALGOLIA_INDEX ?? "agility_content"

// Keep records small: 10 KB is the maximum on the Free plan
const MAX_BODY = 8000

const toObject = (r: SearchRecord) => ({
  ...r,
  objectID: r.id,
  body: r.body.slice(0, MAX_BODY),
  updatedAt: Math.floor(Date.parse(r.updatedAt) / 1000), // numeric, so it can be used for ranking
})

export const searchIndex = {
  async upsert(record: SearchRecord) {
    await client.saveObject({ indexName, body: toObject(record) })
  },

  async upsertMany(records: SearchRecord[]) {
    if (records.length) await client.saveObjects({ indexName, objects: records.map(toObject) })
  },

  async remove(id: string) {
    await client.deleteObject({ indexName, objectID: id })
  },
}

Plug this into the route handler and reindex script from the indexing guide, and publishing in Agility now updates Algolia.

A few things to know:

• Writes are asynchronous. Each call returns a taskID as soon as Algolia has accepted the change, and the record is searchable a moment later. There's no need to wait in a webhook handler. When a script needs the change to be live before continuing, use client.waitForTask({ indexName, taskID }).
• Record size. Algolia limits the size of each record: 10 KB on the Free plan, more on paid plans. Truncating the body, as above, is the simplest fix. For long articles where every paragraph should be findable, split each item into several records instead. Give each one an objectID of ${id}-${n} and a shared parentId, and set distinct: true with attributeForDistinct: "parentId" so each item appears once in results. See Indexing long documents. If you do this, remove must delete every chunk. Use client.deleteBy({ indexName, deleteParams: { filters: parentId:"${id}" } }) with parentId in attributesForFaceting.

Rebuilding the whole index

For a clean rebuild, replaceAllObjects writes everything to a temporary index and then swaps it in atomically, so search never shows a half-built index:

await client.replaceAllObjects({ indexName, objects: allRecords.map(toObject) })

Collect allRecords with the Sync API loop from the indexing guide. Be aware that it copies your index settings, rules and synonyms along with the records, and a very large rebuild temporarily doubles your record count.

Build the search UI

React InstantSearch gives you a search box, results, highlighting, facets and pagination as components. With the Next.js App Router, use InstantSearchNext so results are server-rendered on the first load:

// components/SiteSearch.tsx
"use client"
import Link from "next/link"
import { liteClient as algoliasearch } from "algoliasearch/lite"
import { Configure, Highlight, Hits, SearchBox, Snippet } from "react-instantsearch"
import { InstantSearchNext } from "react-instantsearch-nextjs"

const searchClient = algoliasearch(
  process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
  process.env.NEXT_PUBLIC_ALGOLIA_SEARCH_API_KEY!,
)

function Hit({ hit }: { hit: any }) {
  return (
    <Link href={hit.url}>
      <Highlight attribute="title" hit={hit} />
      <Snippet attribute="body" hit={hit} />
    </Link>
  )
}

export function SiteSearch({ locale }: { locale: string }) {
  return (
    <InstantSearchNext searchClient={searchClient} indexName="agility_content" insights>
      <Configure filters={`locale:"${locale}"`} hitsPerPage={10} />
      <SearchBox placeholder="Search…" />
      <Hits hitComponent={Hit} />
    </InstantSearchNext>
  )
}

// app/[locale]/search/page.tsx
import { SiteSearch } from "@/components/SiteSearch"

export const dynamic = "force-dynamic"

export default async function SearchPage({ params }: { params: Promise<{ locale: string }> }) {
  const { locale } = await params
  return <SiteSearch locale={locale} />
}

• Search as you type in a header — use InstantSearch's <Autocomplete> widget (stable since react-instantsearch 7.41). It replaces the separate @algolia/autocomplete-* packages the previous version of this guide used, which Algolia no longer recommends for new projects.
• Want a finished UI to drop in? Algolia SiteSearch provides ready-made search, dropdown and "Ask AI" experiences built on InstantSearch. Install them with the shadcn CLI or a CDN script.
• Pages Router? Wrap InstantSearch in InstantSearchSSRProvider and use getServerState. See server-side rendering.
• Cost: every keystroke in search-as-you-type is one search request, which is what Algolia bills. InstantSearch handles this sensibly, but keep it in mind for high-traffic sites.
• Analytics: the insights prop sends click and conversion events, which power Algolia's analytics, AI ranking and Recommend.

Keys in the browser

The Search API key is designed to be public, and it can only search. Anyone can still copy it and query your index directly, bypassing your Configure filters. That matters in two cases:

• Content that some visitors shouldn't see. Don't index it into a public index at all.
• Abuse or scraping. Generate a secured API key on your server, with an expiry, a rate limit and forced filters, and pass that to the browser instead:

const securedKey = client.generateSecuredApiKey({
  parentApiKey: process.env.ALGOLIA_SEARCH_API_KEY!, // a search-only key, never the Admin key
  restrictions: { filters: `locale:"en-us"`, validUntil: Math.floor(Date.now() / 1000) + 3600 },
})

AI search options

• Agent Studio — build a conversational assistant that answers from your Agility index, and add it to your site with InstantSearch's <Chat> widget. It's available on every plan. For production you connect your own LLM provider (Anthropic, OpenAI, Azure OpenAI, Gemini and others). See Agent Studio. Ask AI is now part of Agent Studio, so build new assistants on Agent Studio rather than the older Ask AI API.
• NeuralSearch — hybrid keyword and vector search with embeddings managed by Algolia. It's available on the Elevate plan and needs no change to your records or to this integration.
• MCP — a Public MCP server exposes read-only search over your index to AI agents and assistants. If you use an AI coding assistant, Algolia's DevEx MCP gives it up-to-date client code examples.

Plan features change. See Algolia pricing for what's included in each plan.

Alternatives to a webhook

The webhook integration gives you structured records, updated seconds after publishing. Algolia also offers:

• Crawler — crawls your live site on a schedule and builds records from the rendered HTML, with no code in your app. It's a good fit for a pages-only site search when a delay after publishing is acceptable. You can ask it to recrawl specific URLs, but that's rate-limited, so it doesn't replace webhooks on a busy site.
• Push connector — keeps the webhook, but moves record shaping into a transformation function hosted in Algolia (saveObjectsWithTransformation). This is useful when non-developers need to change what gets indexed.

Upgrading from the previous guide

If you built from the earlier version of this page:

1. Upgrade to algoliasearch v5. initIndex is gone, and every method takes indexName instead:

   v4	v5
   import algoliasearch from "algoliasearch"	import { algoliasearch } from "algoliasearch"
   import algoliasearch from "algoliasearch/lite"	import { liteClient as algoliasearch } from "algoliasearch/lite"
   index.saveObject(obj)	client.saveObject({ indexName, body: obj })
   index.saveObjects(objs)	client.saveObjects({ indexName, objects: objs })
   index.deleteObject(id)	client.deleteObject({ indexName, objectID: String(id) })
   index.search(query)	client.searchSingleIndex({ indexName, searchParams: { query } })

   See Algolia's upgrade guide.

2. Verify signatures. Turn on secure delivery for your webhook and verify it, as in the indexing guide.

3. Handle unpublishing. Agility sends Deleted for both unpublish and delete. The earlier example only handled deletes, and it never sent a response in that branch, so the request hung until it timed out.

4. Use locale-aware object IDs. The earlier example used the bare contentID, so locales overwrote each other. Switching to en-us-content-39 style IDs means a full reindex into a fresh index. Use replaceAllObjects.

5. Move to InstantSearch for the UI. <Link><a>…</a></Link> also no longer works in current Next.js; Link renders the <a> itself.

6. Run the full reindex once. The webhook only indexes content published after it was set up.

Troubleshooting

• The webhook returns 400 "Record is too big". Lower MAX_BODY, or split records as described above.
• The webhook returns 403. The write key is missing addObject or deleteObject, or it's restricted to a different index.
• Nothing shows in results. In the Algolia dashboard, open the index and search there. If the records are there, check that searchableAttributes includes the fields and that your Configure filters value matches the record's locale.
• A result is stale. Check the webhook's History in Agility, then run the reindex. See Debugging.

Need help?

Contact us to talk to an expert about this integration.