API Reference

JavaScript API

The FlowSearch widget provides a JavaScript API for programmatic control.

Initialization

// Create instance
const flowSearch = new FlowSearch({
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY'
});

// Initialize (required)
flowSearch.init().then(() => {
  console.log('FlowSearch ready!');
}).catch(error => {
  console.error('Initialization failed:', error);
});

Instance Methods

`init()`

Initialize FlowSearch and enhance DOM elements.

// Returns: Promise<void>
await flowSearch.init();

`search(query)`

Programmatically trigger a search.

// Returns: Promise<SearchResults>
const results = await flowSearch.search('webflow design');
console.log(results.hits);      // Array of result objects
console.log(results.nbHits);    // Total number of results
console.log(results.query);     // The search query

`clear()`

Clear the current search and results.

flowSearch.clear();

`focus()`

Focus the search input.

flowSearch.focus();

`updateConfig(options)`

Update configuration at runtime.

flowSearch.updateConfig({
  debounceMs: 500,
  maxResults: 15
});

`destroy()`

Remove FlowSearch and clean up event listeners.

flowSearch.destroy();

Properties

Property	Type	Description
`isReady()`	boolean	Whether FlowSearch is initialized
`getConfig()`	object	Current configuration
`getElements()`	object	Enhanced DOM elements
`getCurrentQuery()`	string	Current search query

REST API

FlowSearch also provides a REST API for server-side integration.

Authentication

All API requests require your API key in the header:

X-FlowSearch-Key: YOUR_API_KEY

Endpoints

Search

GET /api/v1/search

Query parameters:

Parameter	Type	Description
`q`	string	Search query (required)
`limit`	number	Max results (default: 10)
`page`	number	Page number (default: 1)
`filters`	string	Filter expression

Example request:

curl -X GET "https://api.flowsearch.io/api/v1/search?q=webflow&limit=10" \
  -H "X-FlowSearch-Key: YOUR_API_KEY"

Example response:

{
  "success": true,
  "data": {
    "hits": [
      {
        "id": "page_123",
        "title": "Getting Started with Webflow",
        "description": "Learn the basics of Webflow...",
        "url": "/blog/getting-started-webflow",
        "category": "Tutorial"
      }
    ],
    "nbHits": 24,
    "page": 1,
    "nbPages": 3,
    "processingTimeMs": 12
  }
}

AI Search

GET /api/v1/search/ai

Additional parameters:

Parameter	Description
`stream`	Return streaming response (default: false)
`include_documents`	Include uploaded docs (default: true)
`max_sources`	Max sources to cite (default: 3)

Rate Limits

Plan	Requests/minute
Free	60
Pro	300
Business	600
Enterprise	Custom

Error Responses

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "retryAfter": 60
  }
}

Events

FlowSearch emits custom DOM events you can listen to:

// Listen for FlowSearch events
document.addEventListener('flowsearch:init', (e) => {
  console.log('FlowSearch initialized');
});

document.addEventListener('flowsearch:search', (e) => {
  console.log('Search started:', e.detail.query);
});

document.addEventListener('flowsearch:results', (e) => {
  console.log('Results received:', e.detail.hits);
});

document.addEventListener('flowsearch:click', (e) => {
  console.log('Result clicked:', e.detail.result);
});

document.addEventListener('flowsearch:error', (e) => {
  console.error('Search error:', e.detail.error);
});

TypeScript Support

FlowSearch includes TypeScript definitions:

import FlowSearch, { FlowSearchConfig, SearchResults } from '@flowsearch/widget';

const config: FlowSearchConfig = {
  apiUrl: 'https://api.flowsearch.io',
  apiKey: 'YOUR_API_KEY',
  debounceMs: 300
};

const flowSearch = new FlowSearch(config);

flowSearch.search('query').then((results: SearchResults) => {
  console.log(results.hits);
});