Installation
Add the SDK to your project via your preferred package manager:
# pnpm (recommended)
pnpm add @akropolys/sdk
# npm
npm install @akropolys/sdk
# yarn
yarn add @akropolys/sdkProvider Setup
Wrap your root layout in AkropolysProvider to initialise the vector index, define your target vertical domain, and establish background communication with the Akropolys API:
// app/layout.jsx
import { AkropolysProvider } from '@akropolys/sdk'
export default function RootLayout({ children }) {
return (
<AkropolysProvider
siteId="your-site-id"
apiUrl="https://api.akropolys.io"
apiToken="your-api-token"
vertical="property" // 'commerce' | 'property' | 'motor' | 'blog' | any custom vertical
>
{children}
</AkropolysProvider>
)
}NOTE
Your siteId and apiToken are available in the Akropolys developer dashboard. The vertical prop determines how the assistant structures its queries and filters results for your specific domain.
Entity Auto-Ingest
Call usePageIngest() inside any dynamic details page (products, real estate listings, vehicles, articles). It fires on client-side mount, queuing your raw entity payload to be synced with the semantic vector index in the background — no complex batch jobs or custom data loaders required:
// app/properties/[id]/page.jsx
import { usePageIngest } from '@akropolys/sdk'
export default function PropertyPage({ property }) {
usePageIngest({
id: property.id,
title: property.title,
url: window.location.href,
fields: {
price: property.monthly_rent,
category: property.type,
description: property.description,
specs: property.features,
},
})
return <div>{property.title}</div>;
}Content Indexing
For blogs, news, help centers, and corporate profiles, Akropolys offers a zero-config automated content indexing pipeline. Enabling indexContent listens to route changes, cleans structural noise, and indexes page text in the background.
Place the AkropolysProvider at the root of your application. Enable content extraction by setting indexContent to true:
import { AkropolysProvider } from '@akropolys/sdk'
export default function RootLayout({ children }) {
return (
<html>
<body>
<AkropolysProvider
siteId="your-site-id"
apiUrl="https://api.akropolys.io"
apiToken="your-api-token"
vertical="blog"
indexContent={true}
>
{children}
</AkropolysProvider>
</body>
</html>
)
}For Astro, import and call initAkropolys in a client-side script tag inside your main layout:
<script>
import { initAkropolys } from '@akropolys/sdk';
initAkropolys({
siteId: "your-site-id",
apiUrl: "https://api.akropolys.io",
apiToken: "your-api-token",
indexContent: true
});
</script>How it works (Client-side DOM Extraction)
When indexContent is active, the SDK listens to initial page loads and subsequent SPA routing events (via popstate, pushState, and replaceState). Once a route settles, the SDK clones the page layout target in memory, cleans up structural noise, and vectors the text content under the current URL.
Intelligent Noise Filtering & Extraction Rules
To prevent footer menus and cookie policies from polluting search results, the indexer automatically strips:
- Structural noise tags:
nav,header,footer,iframe - Hidden elements:
[aria-hidden=“true”],template, and elements withdisplay: none - Page assets:
script,style,noscript
Knowledge Enrichment
Upload your own documents — PDFs and Word files (.docx) — and the assistant answers from them. A veterinary site can upload an immunization schedule; a lettings firm can upload its tenancy policy. Akropolys extracts the text, splits it into passages, and indexes them into the same vector store as your catalog and content pages.
Retrieval stays lean: only the top-matching passages for a given question are injected into the model’s context, so a 40-page PDF never bloats the prompt — the assistant pulls just the few paragraphs that actually answer the question.
PLAN
Document upload is a Pro feature. Free and kiosk plans receive HTTP 402 with an upgrade prompt. Each plan includes a number of documents per billing period; uploads beyond the included quota are billed as overage.
Dashboard: the simplest path is the Knowledge → Documents tab in the developer dashboard — drag and drop a file, watch it index, and track quota usage. To automate it, use the REST endpoints below.
# Upload a PDF or .docx (Pro plan or above)
curl -X POST https://api.akropolys.io/v1/sites/your-site-id/knowledge/documents \
-H "Authorization: Bearer your-api-token" \
-F "file=@immunization-schedule.pdf"
# List uploaded documents + quota/overage usage
curl https://api.akropolys.io/v1/sites/your-site-id/knowledge/documents \
-H "Authorization: Bearer your-api-token"
# Delete a document — also removes its passages and vectors
curl -X DELETE https://api.akropolys.io/v1/sites/your-site-id/knowledge/documents/DOCUMENT_ID \
-H "Authorization: Bearer your-api-token"Upload response & processing
A successful upload returns the document’s id, filename, bytes, chunk_count (how many passages it was split into), and a status of ready once indexed. The list endpoint returns each document alongside a usage block (used, included, overage) so you can surface quota state to your team. Scanned, image-only PDFs with no extractable text are rejected with HTTP 422.
Search Component
Drop the SearchBar component anywhere in your UI. It resolves natural language queries against your ingested catalog and returns structured results:
// components/CatalogSearch.jsx
import { SearchBar } from '@akropolys/sdk'
export default function CatalogSearch() {
return (
<SearchBar
placeholder="family SUV under £28k, not diesel"
onResult={(results) => setItems(results)}
/>
)
}TIP
The onEmpty callback fires for every unmatched query — this is your raw intent signal. Log it, store it, act on it.
CLI Diagnostics & Observability
Akropolys includes a lightweight developer CLI (@akropolys/cli) to verify workspace settings, connectivity to the API, and inspect payloads against standard ingestion anti-patterns:
# Install globally or run via npx
npx @akropolys/cli doctor
# Bootstraps configuration (.env helper)
npx @akropolys/cli init
# Preview catalog payloads and check structural warnings
npx @akropolys/cli inspect catalog.jsonAvailable Commands:
init— Runs an interactive setup wizard that asks for your Site ID, API Token, and vertical selection, then automatically generates a configured.envfile.doctor— Validates your local environment variables and checks network reachability to the Akropolys API, returning detailed ping times and connection health.inspect <file>— Statically scans your local JSON data catalog to identify quality degradation patterns (like missing stable identifiers or low-signal payloads) before uploading. Supports standard input piping and a--strictmode for CI pipelines.
UI Components (Kiku)
Akropolys provides a pre-built React UI library, @akropolys/kiku, offering polished search bars, conversational assistants, and checkout modals.
1. Install the packages:
pnpm add @akropolys/sdk @akropolys/kiku2. Import the stylesheet in your layout/app entry:
import '@akropolys/kiku/styles.css';3. Render UI components:
// components/Assistant.jsx
import { KikuChat, KikuButton } from '@akropolys/kiku';
export default function Assistant() {
return (
<div className="assistant-container">
{/* Renders full conversational search widget */}
<KikuChat placeholder="Ask me about our listings..." />
{/* Or renders the floating assistant toggle trigger button */}
<KikuButton />
</div>
);
}HIGHLIGHT
KikuButton features built-in token pacing via requestAnimationFrame for smooth, readable streaming animations, a static streaming caret, and a neutral “Thinking…” loader.
Model Context Protocol (MCP)
@akropolys/mcp is a thin MCP server that exposes your site’s configured intents as MCP tools. Any agent that supports MCP (Claude Desktop, Cursor, custom agents) can search your catalog, read entity details, and trigger your intent actions — using the exact same tool definitions you already configured in the dashboard.
1. Install globally or run with npx:
npm install -g @akropolys/mcp
# or use without installing
npx @akropolys/mcp2. Configure Claude Desktop:
{
"mcpServers": {
"akropolys": {
"command": "npx",
"args": ["-y", "@akropolys/mcp"],
"env": {
"AKROPOLYS_API_URL": "https://api.akropolys.io",
"AKROPOLYS_API_KEY": "your-api-key",
"AKROPOLYS_SITE_ID": "your-site-id"
}
}
}
}3. How it works:
The MCP server reads your site’s intent configuration from the Akropolys API and surfaces each intent as an MCP tool with a name, description, and parameter schema. When an agent calls a tool, the server executes it against your live catalog — search, cart, recall, and any custom intent actions you’ve defined — and streams the result back. No proxying, no separate infrastructure.
SCOPE The MCP server uses the agents access scope. Make sure agent access is enabled for your site in the dashboard under Agents → Access before connecting.
React Hooks Reference
Akropolys React SDK exports headless hooks to manage state, search queries, and chat streams without tying you to predefined styles:
useKiku(options)— Returns message arrays, loading/streaming states,lastAction,lastIntent, and asendcallback that executes SSE token streaming from Kiku. LeveragesrequestAnimationFramepacing internally for smooth, natural typing animations.useSearch()— Manages in-memory Trie autocomplete queries and returnsresultslists.useCart()— Controls client-side shopping cart synchronization and checkout workflows.
Core Types Reference
Types are intentionally lightweight and generic — the platform adapts to your data shape, not the other way around:
// All ingestion payloads accept generic Entity shapes
export type Entity<T extends Record<string, any> = Record<string, any>> = {
url?: string;
id?: string;
} & T;
interface AkropolysConfig {
siteId?: string;
apiUrl?: string;
apiToken?: string;
shopperId?: string;
vertical?: 'commerce' | 'property' | 'motor' | 'blog' | string;
indexContent?: boolean;
display?: Record<string, string>;
}Analytics API
Every query and ingestion item automatically reports metrics to your developer dashboard. The SDK wraps these events to capture:
- Latency metrics — Tracking indexing and search query execution times.
- Intent matching — Capturing unmatched queries so you can identify catalog gaps.
- Sync telemetry — Counting processed, deduplicated, and cached sync operations.
Intent Actions
Intent Actions map a natural language intent (e.g. checkout, booking, apply, subscribe) to a URL on your site. When a user triggers it, the assistant emits that action, resolving the correct target URL and returning it dynamically.
Configuring Intent Actions:
Instead of passing routing configuration in code, you define and manage your mappings in the Intent Actions page in the Akropolys developer dashboard. You can map any custom intent to any destination URL on your domain without redeploying your frontend.
Reacting to Actions in Frontend:
When an intent fires, the SDK handles standard actions (such as cart events or checkout transitions) automatically by dispatching standard events. For custom flows, read lastAction and lastIntent from the useKiku() hook:
// components/CustomChat.jsx
import { useKiku } from '@akropolys/sdk'
import { useEffect } from 'react'
export default function CustomChat() {
const { messages, lastAction, lastIntent, send } = useKiku();
useEffect(() => {
if (!lastAction) return;
if (lastAction.type === 'booking' && lastAction.url) {
window.location.href = lastAction.url;
}
}, [lastAction]);
return (
<div>
{/* your chat UI renders messages and a text input */}
</div>
);
}Standard Window Events Dispatched:
akropolys:cart_updated— Dispatched when a cart-altering action occurs (add, remove, clear), carrying the updated cart snapshot indetail.akropolys:trigger_checkout— Dispatched when a checkout intent is triggered, allowing you to open your custom checkout drawer or overlay.