Your website visitors know what they want. They typed it into your search bar, got three results that mentioned the word "FAQ," and left. That's not a traffic problem. That's a "your search bar is stuck in 2009" problem.

The good news: the gap between "no AI search" and "shipped AI search" is smaller than it's ever been. Here's a clear-eyed look at your options, ordered from fastest to most custom.

What's the fastest way to add AI search with zero code?

If your goal is working AI search on your site today, start here. SurfableAI ships an embeddable widget — a single <script> tag and one attribute.

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

That's it. The widget handles the UI, the semantic search, and the connection to your indexed content. You configure behavior (search vs. chat vs. agent mode) via HTML attributes, not code.

When this is the right call:

You run a marketing site, docs portal, or help center
You don't have a dedicated engineering team
You want results this week, not next quarter
You'd rather spend time on content strategy than infrastructure

The widget supports search, RAG chat, and agentic conversations — all switchable via the data-mode attribute. It's not a dumbed-down version of the API. It's the same engine, pre-wrapped.

When should you use a React component instead?

If you're already running a React app and want your design system to stay intact, the component path makes more sense than the widget. Install the package, pass your API key, and render it inside your existing layout.

npm install @surfable/widget

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

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

The component accepts the same configuration options as the widget. You get full control over placement, styling via CSS vars, and you can compose it with your own input components for complete UI ownership.

When this is the right call:

You have an existing design system
Tailwind / shadcn / your component library is already doing the heavy lifting
You want to co-locate search with other UI logic (filters, navigation, analytics events)

When should you call the API directly?

For teams that need custom result rendering, private-key server-side auth, response filtering, or integration with an existing backend, calling the Surfable API directly is the right move.

Keep the API key server-side. Never expose it to the browser.

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

const { results } = await response.json();

The response gives you ranked content chunks with metadata, source URLs, and relevance scores. You decide what to render, how to rank further, and what to discard.

This is also the right path if you're building:

Multi-tenant SaaS where each customer has their own index
A mobile app that needs search without a browser widget
A backend pipeline that feeds results into another system

When is a custom RAG stack actually worth it?

Building RAG from scratch means managing your own vector database, embedding pipeline, chunking strategy, retrieval logic, re-ranking, prompt engineering, evaluation, and hallucination monitoring. It's a real project.

The typical stack: Postgres with pgvector or Pinecone, an embedding model such as Gemini Embedding 2 or OpenAI text-embedding-3-small, an LLM for generation (GPT-4o, Gemini, Claude), and a backend that ties them together.

When this is actually worth it:

Your content has proprietary structure that general-purpose chunkers don't handle
You have strict data residency requirements that rule out third-party APIs
You're building on top of Surfable and need to extend the retrieval pipeline directly
You have a dedicated ML team and a specific reason to own the entire stack

For everyone else: the custom stack delivers marginally more control in exchange for significantly more operational overhead. Most teams that start here eventually wrap it in an abstraction that looks a lot like a managed service anyway.

Which integration path should you pick?

| Situation | Recommended path | |---|---| | Marketing site, help center, docs | Widget embed | | React app, existing design system | Component | | Custom UI, backend control, private key auth | Direct API | | Strict data residency, proprietary content pipeline | Custom RAG |

The embed and component paths share the same underlying Surfable API. The difference is how much of the plumbing you want to see. Start with the fastest path that meets your requirements — you can always move to a more custom integration later without re-indexing your content. That bias toward faster implementation is getting more rational, not less: the Stanford 2025 AI Index shows how quickly AI usage and investment are accelerating, which shortens the window for shipping a better on-site search experience.

How do you get your content indexed first?

All four paths depend on your content being indexed. Before any search query runs, Surfable needs to crawl and vectorise your site.

The fastest way:

# Point Surfable at your site; it crawls and indexes automatically
POST /ingest
{
  "url": "https://yoursite.com",
  "maxDepth": 2,
  "limit": 500
}

Run this once. Scheduled re-crawls keep the index fresh as your content updates and consume credits when changed content is processed. From that point, your widget, component, or API calls have something to search against.

Frequently Asked Questions

Do I need to know how to code to add AI search to my website?

No. The widget embed is a single <script> tag — no code required. You add it to any page the same way you'd add Google Analytics or a Typeform embed. The search experience is fully functional out of the box.

How long does it take to go from signup to live AI search?

For most sites: under an hour. The ingest job starts indexing your content immediately after you point Surfable at your URL. Once it completes, the widget or API is live and searchable.

What is the difference between the widget and calling the API directly?

The widget is a fully built UI component that handles the interface, API calls, and the search experience. The direct API gives you raw, ranked results to render however you like — no pre-built UI, full control over output. Both draw from the same content index.

Can I switch from the widget to a custom integration later?

Yes. Your content index is independent of the integration method. Switching from the widget to the direct API or a React component doesn't require re-indexing your content.

What is RAG, and do I need it?

Retrieval-Augmented Generation (RAG) is the technology powering AI chat and question-answering. It retrieves relevant content from your index first, then generates a grounded answer from that content. The widget's chat and agent modes use RAG automatically — you don't build or configure it separately.

The gap between "I want AI search" and "my visitors have AI search" is one ingest job and one embed tag. Most teams make it harder than it is. Don't.