Search

Execute text search queries with highlights and facets.

Endpoint

POST /search

Request Body

string

required

Tenant identifier for multi-tenant isolation

string

Optional user identifier for user-level scoping

string

required

Search query string

object

Field filters to narrow results

array

Fields to aggregate for facets (e.g., ["source", "content_type"])

integer

default:"20"

Maximum results to return (1-100)

integer

default:"0"

Pagination offset

Example Request

curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "demo",
    "user_id": "user-1",
    "query": "machine learning",
    "filters": {
      "source": "files"
    },
    "facets_requested": ["source", "content_type"],
    "limit": 10
  }'

Response

array

Array of search hits

Show Hit object

string

Unique identifier

string

Document title

string

Text snippet

array

Highlighted text fragments with <em> tags

number

Relevance score

string

Source system (files, gmail, etc.)

string

Content type

string

Parent item ID

array

Aggregation results

Show Facet object

string

Field name

array

Value counts

Entities mentioned in top hits

integer

Total matching documents

integer

Query execution time in milliseconds

Example Response

{
  "hits": [
    {
      "kos_id": "passage-abc123",
      "title": "Introduction to Machine Learning",
      "snippet": "Machine learning is a subset of artificial intelligence...",
      "highlights": [
        "<em>Machine learning</em> is a subset of artificial intelligence that enables systems to learn"
      ],
      "score": 2.45,
      "source": "files",
      "content_type": "article",
      "item_id": "item-xyz789"
    }
  ],
  "facets": [
    {
      "field": "source",
      "buckets": [
        {"value": "files", "count": 15},
        {"value": "gmail", "count": 3}
      ]
    },
    {
      "field": "content_type",
      "buckets": [
        {"value": "article", "count": 12},
        {"value": "email", "count": 6}
      ]
    }
  ],
  "related_entities": [
    {
      "kos_id": "entity-123",
      "name": "Andrew Ng",
      "type": "person"
    }
  ],
  "total": 18,
  "took_ms": 23
}

Filtering

Use the filters object to narrow results:

{
  "filters": {
    "source": "gmail",
    "content_type": "email"
  }
}

Array values match any:

{
  "filters": {
    "source": ["files", "gmail"]
  }
}

Pagination

Use limit and offset for pagination:

{
  "limit": 20,
  "offset": 40
}

​Search

​Endpoint

​Request Body

​Example Request

​Response

​Example Response

​Filtering

​Pagination

Search

Endpoint

Request Body

Example Request

Response

Example Response

Filtering

Pagination