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

# Query

`POST /v1/knowledge/query`

Search verified knowledge and get back a structured list of matching entities. Same input as
`knowledge_search` — natural language or Dot-Notation Syntax — only the output shape differs.

Returns a structured array of matching results plus entities. The input field is called "input" (not "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, ...)` projects the result to just those fields (always keep an identity field
  like `name`)

- 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": "Which biotech companies were founded after 2020?"}`

`{"input": "companies.industry=fintech.founded_year>=2020"}`

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


Use this when: You want a filtered, structured list of entities back.
NOT for: A researched prose answer with citations — use `knowledge_search` instead (same input,
different output). NOT for: Looking up one specific entity by name — use `entity_search`.

## Request body

- QueryRequest
  - `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.
  - `return_entities` boolean — Whether to return the entities identified in the query response.

## Response `200`

Successful Response

- QueryResponse — Response in case of a successful structured query.
  - `results` object[], required — A list of structured results for the query. Shape and schema will be determined by the query.
  - `entities` EntityMention[], nullable, required — Entities identified in the query response.
    - `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)