Query

curl --request POST \
  --url https://api.cala.ai/v1/knowledge/query \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "input": "companies.industry=fintech.founded_year>=2020"
}
'

import requests

url = "https://api.cala.ai/v1/knowledge/query"

payload = { "input": "companies.industry=fintech.founded_year>=2020" }
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({input: 'companies.industry=fintech.founded_year>=2020'})
};

fetch('https://api.cala.ai/v1/knowledge/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "entities": [
    {
      "entity_type": "Company",
      "id": "e2932ee7-7b57-42b7-8c58-cdfcdf56ceb5",
      "mentions": [
        "Amenitiz"
      ],
      "name": "Amenitiz"
    },
    {
      "entity_type": "Company",
      "id": "e843fc48-8339-4c99-a6e2-e7fb1cc738b1",
      "mentions": [
        "H2SITE"
      ],
      "name": "H2SITE"
    },
    {
      "entity_type": "Company",
      "id": "af3ff4b5-27a9-45d5-8c67-b656cb38e6b8",
      "mentions": [
        "Fracttal"
      ],
      "name": "Fracttal"
    }
  ],
  "results": [
    {
      "company": "Amenitiz",
      "funding_amount": "€38.9M",
      "round_type": "Series B",
      "sector": "Hospitality SaaS",
      "year": 2025
    },
    {
      "company": "H2SITE",
      "funding_amount": "€36M ($37.2M)",
      "round_type": "Series B",
      "sector": "Hydrogen Energy",
      "year": 2025
    },
    {
      "company": "Fracttal",
      "funding_amount": "€29.8M ($35M)",
      "round_type": "Series B",
      "sector": "AI Maintenance",
      "year": 2026
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Too many requests."
}

API v1

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.

POST

knowledge

query

Query

curl --request POST \
  --url https://api.cala.ai/v1/knowledge/query \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "input": "companies.industry=fintech.founded_year>=2020"
}
'

import requests

url = "https://api.cala.ai/v1/knowledge/query"

payload = { "input": "companies.industry=fintech.founded_year>=2020" }
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({input: 'companies.industry=fintech.founded_year>=2020'})
};

fetch('https://api.cala.ai/v1/knowledge/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "entities": [
    {
      "entity_type": "Company",
      "id": "e2932ee7-7b57-42b7-8c58-cdfcdf56ceb5",
      "mentions": [
        "Amenitiz"
      ],
      "name": "Amenitiz"
    },
    {
      "entity_type": "Company",
      "id": "e843fc48-8339-4c99-a6e2-e7fb1cc738b1",
      "mentions": [
        "H2SITE"
      ],
      "name": "H2SITE"
    },
    {
      "entity_type": "Company",
      "id": "af3ff4b5-27a9-45d5-8c67-b656cb38e6b8",
      "mentions": [
        "Fracttal"
      ],
      "name": "Fracttal"
    }
  ],
  "results": [
    {
      "company": "Amenitiz",
      "funding_amount": "€38.9M",
      "round_type": "Series B",
      "sector": "Hospitality SaaS",
      "year": 2025
    },
    {
      "company": "H2SITE",
      "funding_amount": "€36M ($37.2M)",
      "round_type": "Series B",
      "sector": "Hydrogen Energy",
      "year": 2025
    },
    {
      "company": "Fracttal",
      "funding_amount": "€29.8M ($35M)",
      "round_type": "Series B",
      "sector": "AI Maintenance",
      "year": 2026
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Too many requests."
}

Authorizations

X-API-KEY

string

header

required

Body

application/json

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.

Example:

"companies.industry=fintech.founded_year>=2020"

return_entities

boolean

default:true

Whether to return the entities identified in the query response.

Example:

true

Response

Successful Response

Response in case of a successful structured query.

results

Results · object[]

required

A list of structured results for the query. Shape and schema will be determined by the query.

Example:

[
  {
    "company": "Amenitiz",
    "funding_amount": "€38.9M",
    "round_type": "Series B",
    "sector": "Hospitality SaaS",
    "year": 2025
  },
  {
    "company": "H2SITE",
    "funding_amount": "€36M ($37.2M)",
    "round_type": "Series B",
    "sector": "Hydrogen Energy",
    "year": 2025
  },
  {
    "company": "Fracttal",
    "funding_amount": "€29.8M ($35M)",
    "round_type": "Series B",
    "sector": "AI Maintenance",
    "year": 2026
  }
]

entities

EntityMention · object[] | null

required

Entities identified in the query response.

Show child attributes

Search Search Entities