---
title: "Search"
method: POST
path: "/v1/knowledge/search"
tags: ["API v1", "Knowledge"]
---

# Search

`POST /v1/knowledge/search`

Search verified knowledge and get back a sourced, prose answer. Best when you have a question and
want a researched narrative with citations — not a list of entities.

Returns markdown content with explainability, source citations, and matching entities.


Input can be natural language or Dot-Notation Syntax — both work the same here, only the output
shape differs from `knowledge_query`.


Dot-Notation Syntax lets you express filters and structure directly:

- `.` navigates entity/topic → attribute → nested facet (e.g. `companies.industry`)

- `=` `!=` `>` `<` `>=` `<=` filter a facet

- `AND` / `OR` combine multiple values of the *same* field (e.g. `investors=A AND B`,
  `series=A OR B`); chain different fields with `.`

- `order_by=field ASC|DESC` and `limit=N` steer which results surface, not just their order

- `return(f1, f2, ...)` focuses the answer on specific fields (a strict field projection on
  `knowledge_query`)

- Clauses can appear in any order

- Numeric fields may come back as approximate strings (e.g. "over 100M", "~206,753") —
  synthesize, don't treat as exact


Examples:

`{"input": "Who founded Anthropic and what is their background?"}`

`{"input": "people.role=CEO.company.industry=renewable_energy"}`

`{"input": "What regulations affect fintech companies in the EU?"}`


Use this when: You want a sourced, prose answer to a question.
NOT for: A structured list of matching entities — use `knowledge_query` instead (same input,
different output). NOT for: Looking up one specific entity by name — use `entity_search`.

## Request body

- SearchRequest
  - `input` string, required — Natural language question or Dot-Notation Syntax (e.g. "companies.industry=fintech.founded_year>=2020"). Dot-Notation Syntax is not a strict grammar — there is no syntax to get wrong. An empty or fallback result means no match, not a syntax error.
  - `explainability` boolean — Whether to generate explainability for the answer.
  - `return_entities` boolean — Whether to return the entities identified in the answer.

## Response `200`

Successful Response

- Answer — The answer to the user's input with the reasoning steps and the context that support the answer.
  - `content` string, required — A succinct answer to the user's input in Markdown format.
  - `explainability` ReasoningSteps[], nullable, required — A list of reasoning steps to get to that answer.
    - `content` string, required — The content of the reasoning step.
    - `references` string[], required — The UUIDs of the KnowBits referenced in the reasoning step. Must match 'id' fields in context array.
  - `context` KnowBit[], required — A list of facts that support the answer.
    - `id` string, uuid, required — The id of the KnowBit.
    - `content` string, required — The information contained in the KnowBit.
    - `origins` Origin[], required — The origins from which the KnowBit was extracted.
      - `source` Source, required — Organization that provides, creates, or publishes the document, like a web site, a book, a report, etc.
        - `name` string, required — The name or title of the source.
        - `url` string, uri, required — The URL of the source.
      - `document` Document, required — Specific text, report, article, or file that contains the information.
        - `name` string, required — The name or title of the document.
        - `url` string, uri, required — The URL of the document.
      - `breadcrumb` string[], required — Breadcrumb field (always empty for compatibility)
  - `entities` EntityMention[], nullable, required — Entities identified in the answer.
    - `id` string, uuid, required — The ID of the entity
    - `name` string, required — The name of the entity
    - `entity_type` 'Entity' | 'Animal' | 'Award' | 'Organization' | 'Company' | 'EducationalInstitution' | 'IntergovernmentalOrganization' | 'Person' | 'Event' | 'GPE' | 'Country' | 'CountrySubdivision' | 'DependentTerritory' | 'Municipality' | 'Continent' | 'Currency' | 'Industry' | 'FinancialMetric' | 'Group' | 'CorporateEvent' | 'PrivateCompanyFundingRound' | 'Facility' | 'Location' | 'Organism' | 'Plant' | 'Product' | 'Sanction' | 'WorkOfArt' | 'Law' | 'Language' | 'Exchange' | 'Future' | 'Commodity' | 'PositioningMetric' | 'MacroIndicatorPublication' | 'MacroIndicator' | 'ForeignExchangeRate' | 'CountryRegion', required — The type of the entity
    - `mentions` string[], required — Mentions of this entity in the response.

## Other responses

- `422` — Validation Error
- `429` — Too many requests (rate limit exceeded)

---

[API](https://skmtc.net/cala/apis/cala-ai.md) · [All operations](https://skmtc.net/cala/apis/cala-ai/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cala/cala-ai/versions/ee1ba9729aeb/schema)