Search

Perform semantic search across all documents in your workspace.

POST /api/v1/search

Authentication

Requires an API key with the search permission.

Header	Value
X-API-Key	ink_live_abc123...
Content-Type	application/json

Request Body

Field	Type	Required	Default	Description
query	string	Yes	--	The search query. Must be between 1 and 1000 characters.
limit	integer	No	10	Maximum number of results to return. Range: 1--100.
min_score	float	No	0.0	Minimum similarity score threshold. Range: 0.0--1.0. Results below this score are excluded.
document_ids	string[]	No	null	Restrict search to specific documents by their IDs.

Code Examples

cURL

curl -X POST https://api.inherent.systems/api/v1/search \
  -H "X-API-Key: $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={
        "X-API-Key": "ink_live_abc123...",
        "Content-Type": "application/json",
    },
    json={
        "query": "How do I authenticate API requests?",
        "limit": 5,
        "min_score": 0.7,
    },
)

data = response.json()
for result in data["results"]:
    print(f"{result['document_name']}: {result['score']:.2f}")
    print(f"  {result['content'][:100]}...")

JavaScript

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

const data = await response.json();
data.results.forEach((result) => {
  console.log(`${result.document_name}: ${result.score}`);
});

Response

Status: 200 OK

{
  "results": [
    {
      "chunk_id": "a1b2c3d4-0001-4000-8000-000000000001",
      "document_id": "a1b2c3d4-0001-4000-8000-000000000010",
      "document_name": "API Authentication Guide.md",
      "content": "All API requests require authentication using a Bearer token or X-API-Key header. Include your API key in the request header to access any protected endpoint...",
      "score": 0.94,
      "metadata": {
        "category": "documentation"
      }
    },
    {
      "chunk_id": "a1b2c3d4-0001-4000-8000-000000000002",
      "document_id": "a1b2c3d4-0001-4000-8000-000000000010",
      "document_name": "API Authentication Guide.md",
      "content": "To create an API key, navigate to Settings > API Keys in the dashboard. Each key can be scoped with specific permissions...",
      "score": 0.87,
      "metadata": {
        "category": "documentation"
      }
    }
  ],
  "query": "How do I authenticate API requests?",
  "total_results": 2,
  "processing_time_ms": 45.2
}

Response Fields

Field	Type	Description
results	array	Array of matching search results, ordered by score descending
results[].chunk_id	string	Unique identifier for the matched chunk
results[].document_id	string	ID of the parent document
results[].document_name	string	Name of the parent document
results[].content	string	Text content of the matched chunk
results[].score	float	Similarity score between 0 and 1 (higher is more relevant)
results[].metadata	object | null	Document-level metadata, if any was set during upload
query	string	The original search query (echoed back)
total_results	integer	Number of results returned
processing_time_ms	float	Server-side query processing time in milliseconds

Errors

Status	Error Type	Description
400	bad-request	Empty or missing query field
401	unauthorized	Missing or invalid API key
403	forbidden	API key does not have search permission
422	validation-error	Request body failed validation (e.g., limit out of range)
429	rate-limit-exceeded	Rate limit exceeded

Example Error Response

{
  "type": "https://api.inherent.systems/errors/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "The 'query' field is required and must be between 1 and 1000 characters.",
  "instance": "/api/v1/search",
  "trace_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2026-04-03T12:34:56.789Z"
}