Search

Perform semantic search across your knowledge base.

POST /api/v1/search

Request Body

Field	Type	Required	Default	Description
query	string	Yes	-	Search query (1-1000 characters)
limit	integer	No	10	Max results (1-100)
min_score	float	No	0.0	Minimum similarity score (0-1)
document_ids	string[]	No	null	Filter to specific document IDs

Example Request

cURL

curl -X POST https://api.inherent.systems/api/v1/search \
  -H "Authorization: Bearer $INHERENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I authenticate API requests?",
    "limit": 5,
    "min_score": 0.7
  }'

Python

import requests

response = requests.post(
    "https://api.inherent.systems/api/v1/search",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "query": "How do I authenticate API requests?",
        "limit": 5,
        "min_score": 0.7
    }
)

JavaScript

const response = await fetch('https://api.inherent.systems/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'How do I authenticate API requests?',
    limit: 5,
    min_score: 0.7,
  }),
});

Response

{
  "results": [
    {
      "chunk_id": "chunk_abc123",
      "document_id": "doc_xyz789",
      "document_name": "API Authentication Guide",
      "content": "All API requests require authentication using a Bearer token. Include your API key in the Authorization header...",
      "score": 0.94,
      "metadata": {
        "category": "documentation"
      }
    },
    {
      "chunk_id": "chunk_def456",
      "document_id": "doc_xyz789",
      "document_name": "API Authentication Guide",
      "content": "To create an API key, navigate to Settings > API Keys in the dashboard...",
      "score": 0.87,
      "metadata": {
        "category": "documentation"
      }
    }
  ],
  "query": "How do I authenticate API requests?",
  "total_results": 2,
  "processing_time_ms": 45.2
}

Filtering by Document

Filter search results to specific documents using the document_ids parameter:

{
  "query": "authentication",
  "document_ids": ["doc_xyz789", "doc_abc123"]
}

Planned Feature

Advanced metadata filtering with operators ($eq, $gt, $in, etc.) is planned for a future release. Currently, you can filter by document_ids only.

Response Fields

Field	Type	Description
results	array	Matching search results
results[].chunk_id	string	Chunk ID
results[].document_id	string	Parent document ID
results[].document_name	string	Parent document name
results[].content	string	Chunk text content
results[].score	float	Similarity score (0-1)
results[].metadata	object	Document metadata (may be null)
query	string	The original search query
total_results	integer	Total number of results returned
processing_time_ms	float	Query processing time in milliseconds

Coming Soon -- Hybrid Search

Combining semantic and keyword search via a hybrid parameter is planned for a future release.

Coming Soon -- Point-in-Time Queries

Querying your knowledge base as it existed at a specific time via an as_of parameter is planned for a future release.

Errors

Code	Description
400	Invalid query or parameters
401	Missing or invalid API key
422	Request validation failed
429	Rate limit exceeded