Your Website’s Second Act Starts Now
With Webless, boost engagement, increase conversions, and cut CAC in under 30 minutes—while laying the foundation for what comes next: Generative Engine Optimization.
Thank you! Your submission has been received!
.png)
21 March, 2025
Building a Custom Frontend on Webless: Installing via SDK/API and Using Claude Code to Move Faster
The default Webless JavaScript embed gets you live in 10 minutes. For most marketing teams, that's exactly right. But some teams need more — a search experience woven into a bespoke React app, a native mobile surface, or a product shell where a floating widget simply doesn't fit. That's when you move past the snippet and start calling the Webless API directly.
This article covers the full path: why teams go custom, how to wire up the Webless API/SDK, and how to use Claude Code in 2026 to scaffold the frontend fast instead of writing boilerplate by hand.
Why Teams Go Past the Default Embed
The JS snippet is a deliberate product decision. It requires no engineering sprint, works on any HTML page, and gives marketing teams full control without touching code. For most Webless customers, it's the right call.
Custom frontend work makes sense when:
- You need full design control. The widget lives inside a design system with strict component standards. You want search results rendered as cards, modals, or inline panels that match your existing UI — not a floating overlay.
- You're building on a non-web surface. Native iOS, Android, or a desktop Electron app can't run a JS embed. You need to call an HTTP endpoint directly.
- Search belongs inside an application shell. If your product has an authenticated dashboard or a docs portal with its own navigation, you want search results appearing inside that shell, not on top of it.
- You're composing Webless with other data sources. Some teams want to merge Webless semantic results with results from an internal database or product catalog, then render a unified response. That requires calling the API and handling the response yourself.
None of these are edge cases. They're common patterns for engineering-led teams at B2B SaaS companies who've already decided Webless is the right semantic search backend.
Installing via API/SDK: The Core Pattern
Webless exposes a semantic search API that your frontend calls directly. The drop-in snippet is a thin wrapper around that same API. When you go custom, you're calling it yourself and owning the presentation layer.
Authentication and API Key Setup
Start at docs.webless.ai for the authoritative reference. The general pattern:
- Generate an API key from your Webless dashboard.
- Pass the key in the request header (
Authorization: Bearer YOUR_API_KEY). - Scope the key to your site's index. If you're on Enterprise with multiple domains, each index has its own identifier.
Keep your API key server-side or in an environment variable. Never expose it in client-side JavaScript that ships to the browser.
Hitting the Semantic Search Endpoint
The core call is a POST to the search endpoint with a natural-language query string and your site index ID. The response returns ranked results with title, excerpt, URL, and intent classification metadata.
Pseudocode for illustration (check docs.webless.ai for exact method signatures):
// Illustrative — not a copy-paste production snippet
const results = await webless.search({
query: visitorQuery,
siteId: process.env.WEBLESS_SITE_ID,
limit: 8
});
The response includes a results array and, depending on your plan, intent signal data attached to each result. That intent data is what lets you route visitors to the right CTA programmatically rather than defaulting to a generic "contact us" link.
Handling Visitor Intent Data
Each result can carry an intent classification: informational, navigational, or transactional. Your frontend uses this to decide what to render alongside the result. A transactional query gets a demo CTA. An informational query surfaces a related article. This logic lives in your frontend code, not in the Webless widget configuration.
// Illustrative CTA routing
function getCTA(intentType) {
if (intentType === 'transactional') return <BookDemoButton />;
if (intentType === 'navigational') return <PageLink />;
return <RelatedArticleCard />;
}
Using Claude Code to Scaffold the Frontend Fast
Writing a search UI from scratch means: query input component, debounce logic, loading states, result rendering, empty states, error handling, CTA routing, and accessibility. That's a half-day of boilerplate before you've written a line of real product logic.
Claude Code changes this. Feed it the Webless API reference from docs.webless.ai, describe your stack (React, Next.js, Vue, whatever), and prompt it to generate the full search component in one pass.
A Practical Prompting Pattern
Paste the relevant API response schema into your Claude Code context, then prompt:
"Generate a React search component that calls the Webless semantic search API. The component should debounce input, display a loading state, render results as cards with title, excerpt, and URL, and route a CTA button based on the intentType field in each result. Use TypeScript. Style with Tailwind."
Claude Code will scaffold the full component. Your job is to review the output, verify the API call matches the actual endpoint from docs.webless.ai, and wire it into your app shell. You're not debugging generated boilerplate from scratch — you're reviewing and iterating.
This is the 2026 pattern: the developer owns the architecture decisions and the review, Claude Code handles the scaffolding velocity.
Iterating on the Component
Once the base component exists, targeted prompts take you the rest of the way:
- "Add keyboard navigation to the results list"
- "Add an empty state that shows three suggested queries when no results return"
- "Extract the CTA routing logic into a separate hook"
Each iteration takes seconds instead of minutes. For teams building on tight timelines, that compounds quickly.
Webless MCP Access for Agentic Workflows
If your team is on the Pro plan, Webless includes MCP (Model Context Protocol) access. This matters if you're building agentic or AI-driven workflows that need to query Webless data programmatically — for example, an internal tool that surfaces visitor intent signals to a sales team, or an AI assistant that uses your site's indexed content as a knowledge source.
MCP access lets AI agents call Webless as a tool inside an agentic pipeline, not just as a search endpoint for a human-facing UI. It's a distinct use case from the custom frontend pattern, but worth knowing about if you're building on Pro.
Both MCP and the Insights Engine (content gap detection and intent classification at the analytics level) are Pro and above features. Neither is available on the Growth plan.
Architecture Summary
The pattern is straightforward: Webless handles semantic indexing, search, and intent classification. Your frontend handles presentation, routing, and UX. The two are decoupled. You call the API, you own the render.
That decoupling also means you can swap your frontend framework without touching your Webless configuration. Your site's content stays indexed, intent data keeps accumulating, and your analytics dashboard keeps tracking visitor behavior regardless of what's happening on the presentation layer.
FAQs
Do I need a specific Webless plan to access the API directly?
The semantic search API is available on all paid plans. The Insights Engine, HubSpot integration, and MCP access are Pro and above. Federated search across multiple domains is Enterprise only. Check your plan at webless.ai or review docs.webless.ai for endpoint availability by tier.
Can I use the API alongside the JS embed on the same site?
Yes. Some teams use the embed on public marketing pages and call the API directly inside an authenticated product area. The same site index serves both.
What does the Webless API response look like?
The response includes a ranked array of results with title, excerpt, URL, and intent metadata. The exact schema is documented at docs.webless.ai. Use that reference when prompting Claude Code to generate your frontend component.
Is Claude Code the only AI coding tool that works well for this?
No. Any AI coding assistant that can ingest an API reference and generate typed components will work. Claude Code is well-suited to this pattern in 2026 because of its context window and ability to reason about API schemas, but the scaffolding approach applies to any similar tool.
What's Webless MCP and when should I use it?
MCP (Model Context Protocol) access on the Pro plan lets AI agents call Webless as a tool in an agentic pipeline. Use it when you're building an AI-driven workflow that needs to query your site's indexed content or intent data programmatically — rather than rendering a search UI for a human visitor.
How do I keep my API key secure in a frontend app?
Route API calls through a server-side function or API route (a Next.js API route or an Edge Function, for example) so your Webless API key never ships to the browser. The client calls your server endpoint; your server calls Webless.
Where do I find the authoritative API documentation?
All endpoint references, request/response schemas, and authentication details live at docs.webless.ai. The pseudocode examples in this article are illustrative. Always verify method signatures and field names against the live documentation before shipping.
The custom frontend path is straightforward once the architecture clicks: Webless as the semantic search and intent backend, your stack as the presentation layer, and Claude Code as the tool that gets you from zero to a working component in a fraction of the time. Start at docs.webless.ai for the API reference, then build.
Blogs you may like
5 min read
Rakesh Kakati