curl --request POST \
  --url https://api.cala.ai/v1/knowledge/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "input": "Who founded Anthropic and what is their background?"
}
'

import requests

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

payload = { "input": "Who founded Anthropic and what is their background?" }
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: 'Who founded Anthropic and what is their background?'})
};

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

{
  "content": "**Altano Energy (Spain)** — Madrid-based, developing renewable energy projects across Spain. Altano secured €60M Series C in 2025 from M&G Investments and Pioneer Point Partners.",
  "context": [
    {
      "content": "Altano Energy - €60m (Series C, Jul 2025). Develops and operates renewable energy projects across Spain...",
      "id": "732e1954-9538-4fbc-a565-db2f8c07ad4e"
    }
  ],
  "entities": [
    {
      "entity_type": "Company",
      "id": "0abe9580-5abb-46df-9506-5dc784520b69",
      "mentions": [
        "Altano Energy",
        "Altano"
      ],
      "name": "Altano Energy"
    }
  ],
  "explainability": [
    {
      "content": "Altano Energy secured a €60 million Series C round in July 2025 from Pioneer Point Partners and M&G Investments.",
      "references": [
        "f22a1a96-6234-48d7-95c2-8b049f00fdab"
      ]
    }
  ]
}

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

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

API v1

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.

POST

knowledge

curl --request POST \
  --url https://api.cala.ai/v1/knowledge/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "input": "Who founded Anthropic and what is their background?"
}
'

import requests

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

payload = { "input": "Who founded Anthropic and what is their background?" }
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: 'Who founded Anthropic and what is their background?'})
};

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

{
  "content": "**Altano Energy (Spain)** — Madrid-based, developing renewable energy projects across Spain. Altano secured €60M Series C in 2025 from M&G Investments and Pioneer Point Partners.",
  "context": [
    {
      "content": "Altano Energy - €60m (Series C, Jul 2025). Develops and operates renewable energy projects across Spain...",
      "id": "732e1954-9538-4fbc-a565-db2f8c07ad4e"
    }
  ],
  "entities": [
    {
      "entity_type": "Company",
      "id": "0abe9580-5abb-46df-9506-5dc784520b69",
      "mentions": [
        "Altano Energy",
        "Altano"
      ],
      "name": "Altano Energy"
    }
  ],
  "explainability": [
    {
      "content": "Altano Energy secured a €60 million Series C round in July 2025 from Pioneer Point Partners and M&G Investments.",
      "references": [
        "f22a1a96-6234-48d7-95c2-8b049f00fdab"
      ]
    }
  ]
}

{
  "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:

"Who founded Anthropic and what is their background?"

explainability

boolean

default:true

Whether to generate explainability for the answer.

Example:

true

return_entities

boolean

default:true

Whether to return the entities identified in the answer.

Example:

true

Response

Successful Response

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.

Example:

"**Altano Energy (Spain)** — Madrid-based, developing renewable energy projects across Spain. Altano secured €60M Series C in 2025 from M&G Investments and Pioneer Point Partners."

explainability

ReasoningSteps · object[] | null

required

A list of reasoning steps to get to that answer.

Show child attributes

context

KnowBit · object[]

required

A list of facts that support the answer.

Show child attributes

entities

EntityMention · object[] | null

required

Entities identified in the answer.

Show child attributes

Retrieve Entity Query