Search API

Search across your indexed documents using the Search API.

Search Documents

Endpoint

POST /api/v1/search

Request Body

{
  "query": "How do I configure the database?",
  "collections": ["col_abc123"],
  "limit": 10,
  "filters": {
    "topics": ["engineering"],
    "dateRange": {
      "start": "2024-01-01",
      "end": "2024-12-31"
    }
  }
}

Parameters

Parameter	Type	Required	Description
query	string	Yes	Search query
collections	string[]	No	Collection IDs to search
limit	number	No	Max results (default: 10, max: 100)
offset	number	No	Pagination offset
min_score	number	No	Minimum relevance score threshold (0-1). Results below this score are filtered out. Default: 0.5
filters	object	No	Filter criteria
rerank	boolean	No	Enable reranking (default: true)

Filters Object

Field	Type	Description
topics	string[]	Filter by topics
departments	string[]	Filter by departments
languages	string[]	Filter by languages
dateRange	object	Date range filter
sources	string[]	Filter by connector IDs

Response

{
  "data": {
    "results": [
      {
        "id": "doc_xyz789",
        "title": "Database Configuration Guide",
        "content": "To configure the database...",
        "score": 0.95,
        "metadata": {
          "source": "Confluence",
          "collection": "Engineering Docs",
          "createdAt": "2024-03-15T10:00:00Z"
        },
        "highlights": [
          "To <mark>configure</mark> the <mark>database</mark>..."
        ]
      }
    ],
    "total": 42,
    "facets": {
      "topics": [
        { "value": "database", "count": 15 },
        { "value": "configuration", "count": 12 }
      ]
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "took": 145
  }
}

Example Usage

cURL

curl -X POST https://your-domain.com/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database configuration",
    "limit": 5
  }'

JavaScript

const results = await client.search({
  query: 'database configuration',
  collections: ['col_abc123'],
  limit: 5,
  filters: {
    topics: ['engineering']
  }
});

Python

results = client.search(
    query="database configuration",
    collections=["col_abc123"],
    limit=5,
    filters={"topics": ["engineering"]}
)

Advanced Search

Hybrid Search

Enable both semantic and keyword search:

{
  "query": "error code ERR_CONNECTION_REFUSED",
  "hybridSearch": true,
  "hybridWeight": 0.7
}

Query Expansion

Enable automatic query expansion:

{
  "query": "login issues",
  "queryExpansion": true
}

Minimum Score Filtering

Filter out low-relevance results using min_score:

{
  "query": "database setup",
  "min_score": 0.7
}

The min_score parameter accepts values from 0 to 1:

• 0.5 (default): Balanced filtering, removes results below 50% relevance
• 0.7: Strict filtering, only high-quality matches
• 0.3: Lenient filtering, includes more results
• 0: No filtering, returns all results

This is useful when you want to ensure search results meet a quality threshold, reducing noise from loosely related content.

Error Responses

Code	Description
400	Invalid request parameters
401	Authentication required
403	Insufficient permissions
429	Rate limit exceeded

Faceted Search

Endpoint

POST /api/v1/search/faceted

Perform a search with faceted filtering and aggregation.

Get Facets

GET /api/v1/search/facets

Returns available facets and their values for the current collection.

Next Steps

• Chat API - Conversational search
• Documents API - Document management