SurfableAI
Sign inSignup
All docs
Integrations2 min readUpdated March 19, 2026

Integrations

Three ways to add Surfable to your site — HTML widget, React component, or direct API.

Three ways to add Surfable to your site — pick the one that fits your stack.

Prerequisites

  • An API key from Dashboard → API Keys
  • A public key (prefixed pk_) for client-side embeds, or a secret key (prefixed sk_) for server-side calls

HTML Embed Widget

One script tag. Works on any website, no framework required.

<script
  src="https://cdn.surfable.ai/widget.js"
  data-api-key="your_public_key"
  data-mode="search"
></script>

Set data-mode to search, chat, or agent.

The widget renders a floating button in the bottom-right corner by default. Style it via CSS variables — see the widget README for the full token list.

React Component

Drop into any React or Next.js app. Fully styleable via CSS variables.

npm install @surfable/widget

import { SurfableSearch } from '@surfable/widget';

export function SiteSearch() {
  return (
    <SurfableSearch
      apiKey={process.env.NEXT_PUBLIC_SURFABLE_KEY}
      mode="search"
    />
  );
}

Available mode values: search, chat, agent.

Direct API (Server-Side)

Full control. Keep your API key server-side — never expose it to the browser.

// Next.js / Hono / Express — same pattern
const response = await fetch('https://api.surfable.ai/rag', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.SURFABLE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: userQuery }),
});

const { answer, citations } = await response.json();

Use /rag for single-turn grounded answers. Use /agent/chat/stream for multi-step agentic conversations. Use /search if you only need the retrieved chunks without a generated answer.

Next Steps