# Entities
Source: https://docs.cala.ai/api-reference/api-v1/entities
https://api.cala.ai/openapi.json post /v1/entities/{entity_id}
Get typed entity data by its numeric UUID — company, person, place, law, financial instrument, and
more (the schema spans many domains, illustrative not exhaustive) — in two modes:
- **Coarse (no body):** returns only the default property set. No relationships, no numerical
observations. Use only when a rough profile is enough.
- **Projection (body):** name exact `properties`, `relationships`, and `numerical_observations` to
get back. The only way to get relationships or time-series data, and the most token-efficient
read. Available fields vary by entity type and must be *queryable* for that specific entity — run
`entity_introspection` first to discover them; projecting blind wastes round-trips and may hit
empty or non-queryable edges.
Pass the entity UUID in the URL path (e.g. `POST /entities/{entity_id}`). Optionally send a JSON body
to specify which properties and relationships to return; if omitted, default properties are returned.
Examples (path + optional body):
`POST /entities/c6772802-bdbc-4778-91e9-cd3d27d008d5`
Optional body: `{"properties": ["name", "aliases", "registered_address", "employee_count"], "relationships": {"outgoing": {"IS_ULTIMATE_PARENT": {"limit": 5}}, "incoming": {"IS_CEO_OF": {}}}}`
Use this when: You already have an entity UUID (from `entity_search`, `knowledge_search`, or `knowledge_query`
results) and need entity data. Use `entity_search` first if you only have a name, and `entity_introspection`
first if you need a projection.
# Entity Introspection
Source: https://docs.cala.ai/api-reference/api-v1/entity-introspection
https://api.cala.ai/openapi.json get /v1/entities/{entity_id}/introspection
Get the field schema for a real-world entity by its numeric UUID — the schema spans many domains,
illustrative not exhaustive. Use to look up / find out what an entity is queryable for before
pulling its profile. Returns the available properties, relationships, and numerical observations
you can request from `entity_retrieval`.
Examples:
`GET /entities/c6772802-bdbc-4778-91e9-cd3d27d008d5/introspection`
`GET /entities/e5bb591a-d308-4aa5-9672-96046d366cde/introspection`
Use this when: You have an entity UUID and need to discover which attributes and relationships exist before
querying. Use `entity_retrieval` to fetch data, or `entity_search` first if you only have a name.
# Query
Source: https://docs.cala.ai/api-reference/api-v1/query
https://api.cala.ai/openapi.json 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`.
# Search
Source: https://docs.cala.ai/api-reference/api-v1/search
https://api.cala.ai/openapi.json 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`.
# Search Entities
Source: https://docs.cala.ai/api-reference/api-v1/search-entities
https://api.cala.ai/openapi.json get /v1/entities
Find real-world entities by name with fuzzy matching — spans many domains and keeps growing:
business (companies, investors, funding rounds, M&A, industries, products), people, legal (laws,
regulations, sanctions), geography (countries, places), finance/macro (financial metrics, macro
indicators, FX rates), and more — treat this list as illustrative, not exhaustive. Use for "look up
X" / "who/what is X" / "X's profile, properties, or relationships" when you know (or partially know)
the name. Optionally filter by entity type.
Returns an array of matching entities with IDs that feed `entity_retrieval` (entity data) and
`entity_introspection` (available fields).
Examples:
`{"name": "OpenAI"}`
`{"name": "Elon Musk", "entity_types": ["Person"]}`
`{"name": "Berlin", "entity_types": ["GPE"]}`
`{"name": "GDPR", "entity_types": ["Law"]}`
Use this when: You know the name and want the entity ID or a quick profile. Use `knowledge_query`
instead for attribute-based filtering without a name.
# Retrieve Entity
Source: https://docs.cala.ai/api-reference/entities
POST /v1/entities/{entity_id}
Retrieve an entity by its UUID.
Returns detailed information including legal name, industry, founders, executives, headquarters, employee count, and more.
Pass the entity UUID in the URL path (e.g. `POST /entities/{entity_id}`). Optionally send a JSON body to specify which properties and relationships to return; if omitted, default properties are returned.
Use the ***Entity Introspection*** endpoint to see which properties and relationships can be queried for an entity.
Examples (path + optional body):
`POST /entities/c6772802-bdbc-4778-91e9-cd3d27d008d5`
Optional body: `{"properties": ["name", "aliases", "registered_address", "employee_count"], "relationships": {"outgoing": {"IS_ULTIMATE_PARENT": {"limit": 5}}, "incoming": {"IS_CEO_OF": {}}}}`
Use this when you already have an entity UUID (from `entity_search`, `knowledge_search`, or `knowledge_query` results) and need the complete profile. Use `entity_search` first if you only have a name.
# Entity Introspection
Source: https://docs.cala.ai/api-reference/entity-introspection
GET /v1/entities/{entity_id}/introspection
Get the field schema for an entity by its UUID.
Returns the available properties, relationships, and numerical observations you can use when querying the entity with ***Retrieve Entity***.
Examples:
`GET /entities/c6772802-bdbc-4778-91e9-cd3d27d008d5/introspection`
`GET /entities/e5bb591a-d308-4aa5-9672-96046d366cde/introspection`
Use this when you have an entity UUID and need to discover which attributes and relationships exist before querying. Use `retrieve_entity` for the full profile, or `entity_search` first if you only have a name.
# Query
Source: https://docs.cala.ai/api-reference/query
POST /v1/knowledge/query
Get structured, typed JSON rows plus matching entities from Cala's knowledge base.
Accepts either a Cala QL expression or a natural-language question as input — both produce the same structured response shape.
Examples:
`{"input": "startups.location=Spain.funding＞10M.funding＜=50M"}`
`{"input": "companies.industry=fintech.founded_year＞=2020"}`
`{"input": "people.role=CEO.company.industry=AI"}`
`{"input": "What are the biggest AI startups in Europe by funding?"}`
Use this when you want structured, tabular data for programmatic use. Use `knowledge_search` when you want a natural-language answer instead. To look up a known entity by name use `entity_search`.
# Search
Source: https://docs.cala.ai/api-reference/search
POST /v1/knowledge/search
Get a succinct, token-optimized answer in natural-language markdown, with explainability, source citations, and matching entities.
Accepts either a Cala QL expression or a natural-language question as input — both produce the same response shape.
Examples:
`{"input": "What are the biggest AI startups in Europe by funding?"}`
`{"input": "Who founded Stripe and what is their background?"}`
`{"input": "What regulations affect fintech companies in the EU?"}`
Use this when you want a natural-language answer with sources and explainability. Use `knowledge_query` when you want structured, tabular rows instead. Use `entity_search` if you just need to find an entity by name.
# Search Entities
Source: https://docs.cala.ai/api-reference/search-entities
GET /v1/entities
Find entities by name with fuzzy matching when you know (or partially know) an entity's name.
Optionally filter by entity type. Returns an array of matching entities, each with an `id`, `name`, `entity_type`, and a `description` (when available) — use the `id` to pass to ***Retrieve Entity*** for full profiles.
Examples:
`GET /v1/entities?name=OpenAI`
`GET /v1/entities?name=Tim+Cook&entity_types=Person`
`GET /v1/entities?name=Berlin&entity_types=GPE&entity_types=Location&limit=5`
Use this when you know the name and want the entity ID or basic info. Use `retrieve_entity` with the returned ID for full details. Use `knowledge_query` when you want a structured, tabular answer, or `knowledge_search` for a succinct natural-language answer.
# Natural Language Answer
Source: https://docs.cala.ai/features/natural-language-answer
Returns a **succinct, token-optimized answer in natural-language markdown**, with full explainability, source citations, and extracted entities. Use `knowledge_search` (`POST /v1/knowledge/search`) when you need a human-readable answer rather than raw data.
Input can be a **Cala QL expression** or a **natural-language question** — both produce the same response shape. See the [Structured Answer](/features/structured-answer) page for the full QL syntax reference.
* Automatically identifies and extracts entities from results
* Every claim is traceable back to its source documents
## Example
```json theme={null}
{"input": "What are the most promising climate tech startups in Southern Europe?"}
```
Every response includes four parts:
A succinct, structured answer in markdown — ready to use directly.
```markdown theme={null}
## Spanish Startups with >€10M Funding
### Renewable Energy & Deep Tech
**Altano Energy** — Madrid-based, developing renewable energy projects
across Spain. Secured €60M Series C in 2025 from M&G Investments and Pioneer
Point Partners.
**BeePlanet Factory** — Navarre-based, manufactures energy storage from
EV batteries. Raised €5M, building BeeCycle recycling plant with 10,000 tons/year
capacity by 2026.
**Matteco** — Paterna-based, advanced materials for green hydrogen.
€16.3M raised.
### Market Trends
**Spain** leads Southern Europe with 16 cleantech VC deals in Q1 2025.
**Italy** and **Portugal** emerging as hubs via EU Innovation Fund projects.
**Cleantech for Iberia** drove a 37% increase in clean tech investment.
```
Every claim in the answer is traced back to specific source documents — so you know exactly *why* something was said.
```json theme={null}
[
{
"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"]
},
{
"content": "BeePlanet Factory manufactures energy-storage systems from second-life EV batteries and raised approximately $5.3 million.",
"references": ["521038fd-3c36-4fd4-a6e3-9aa2c0be598d"]
},
{
"content": "Spain accounts for the largest share of cleantech VC activity in Southern Europe, recording 16 deals in Q1 2025.",
"references": ["27735c7a-f365-48f7-9db4-cf406ce7033e"]
}
]
```
Each `reference` UUID links to a source document in the Sources section below.
Full provenance for every claim — publisher, article title, and URL. Nothing is a black box.
```json theme={null}
[
{
"id": "f22a1a96-6234-48d7-95c2-8b049f00fdab",
"content": "Altano Energy – €60m (Series C, Jul 2025). Develops and operates renewable energy projects across Spain...",
"origins": [
{
"source": {"name": "Impact Loop", "url": "https://www.impactloop.com/"},
"document": {
"name": "Europe's top 25 climate tech funding rounds this year",
"url": "https://www.impactloop.com/artikel/europe-s-25-largest-climate-tech-fundraises-funding-2025-and-the-investors-behind-them"
}
}
]
},
{
"id": "521038fd-3c36-4fd4-a6e3-9aa2c0be598d",
"content": "Matteco: $16.3m raised. Producer of advanced materials for green hydrogen...",
"origins": [
{
"source": {"name": "Seedtable", "url": "https://www.seedtable.com/"},
"document": {
"name": "11 Best Climate Tech Green Tech Startups in Spain - 2025",
"url": "https://www.seedtable.com/best-climate-tech-green-tech-startups-in-spain"
}
}
]
},
{
"id": "27735c7a-f365-48f7-9db4-cf406ce7033e",
"content": "Cleantech VC deals took place in 17 of 27 EU member states in Q1 2025. Germany led with 36 deals, followed by Netherlands and France (20 each), Spain (16)...",
"origins": [
{
"source": {"name": "Cleantech for Europe", "url": "https://www.cleantechforeurope.com/"},
"document": {
"name": "Cleantech Q1 Briefing 2025",
"url": "https://www.cleantechforeurope.com/publications/cleantech-q1-briefing-2025"
}
}
]
}
]
```
Every entity mentioned is automatically identified, typed, and assigned a Cala UUID — ready to query further with `retrieve_entity`.
```json theme={null}
[
{"id": "d6b818c0-1d2c-47ca-a7d3-5b5c35635769", "name": "Altano Energy", "entity_type": "Organization"},
{"id": "c455f44f-6cb1-47b9-bf06-3cffac130dc4", "name": "BeePlanet Factory", "entity_type": "Organization"},
{"id": "37b9cc58-fd82-4637-a9f9-8409e3e52872", "name": "Matteco", "entity_type": "Organization"},
{"id": "a44ea7f1-2ce8-462a-9548-0ab4d85780de", "name": "Spain", "entity_type": "GPE"},
{"id": "56eb4d13-69c8-45d6-aae3-ff2147d2c157", "name": "Madrid", "entity_type": "GPE"},
{"id": "9ed04484-4df3-47f6-bd77-4e4e50395fa4", "name": "M&G Investments", "entity_type": "Organization"},
{"id": "6f6532d5-61e8-4f34-b4fe-15c50c57ce4e", "name": "Pioneer Point Partners", "entity_type": "Organization"},
{"id": "5fefdf5c-cf11-4980-8cc2-5f9ece2bf247", "name": "Navarre", "entity_type": "GPE"},
{"id": "99dfa2e6-c4ec-4f0e-8501-f35f47d9a764", "name": "BeeCycle", "entity_type": "Facility"},
{"id": "214f2f14-00a2-4812-bcf6-c95a7f4fc990", "name": "Barcelona", "entity_type": "GPE"},
{"id": "4f1235e7-f38d-44af-bcab-d66f3956c577", "name": "Italy", "entity_type": "GPE"},
{"id": "f223b71f-8e67-4493-a4a4-98256f5132f7", "name": "Portugal", "entity_type": "GPE"},
{"id": "6fbaeb38-4b5e-4de2-8f89-40494584d38d", "name": "European Union Innovation Fund", "entity_type": "Organization"},
{"id": "38132d67-d0a2-4f5f-a1a6-f49f6ba8a293", "name": "Cleantech for Iberia", "entity_type": "Organization"}
]
```
Use these UUIDs to get full entity profiles: `POST /v1/entities/d6b818c0-1d2c-47ca-a7d3-5b5c35635769` returns everything Cala knows about Altano Energy.
## Query language input also works
You can also send a plain question — the response shape is identical:
```json theme={null}
{"input": "startups.location=Spain.funding>10M"}
```
## What you get back
| Field | Description |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| `content` | A succinct markdown answer with structured sections |
| `explainability` | Reasoning chain — each claim linked to specific source documents by UUID |
| `context` | Source documents with full provenance: publisher name, article title, URL |
| `entities` | Every entity mentioned, with Cala UUIDs and types (Company, Organization, GPE, Facility, etc.) |
# Retrieve Entity
Source: https://docs.cala.ai/features/retrieve-entity
The retrieve entity endpoint gives your agent comprehensive access to all the information we know about a specific entity. This endpoint:
* Delivers structured, schema-validated data about any entity
* Provides complete entity profiles with all available attributes or requested entity properties and relationships
* Ensures data consistency through proper schema validation
Once you have an entity UUID (from `entity_search`, `knowledge_search`, or `knowledge_query`), retrieve everything Cala knows about it:
## Example:
`POST /entities/c6772802-bdbc-4778-91e9-cd3d27d008d5`
or if you want to query only some of the entity properties add a request body with the desired entity fields:
```json theme={null}
{"properties": ["name", "cik", "lei"]}
```
A complete, structured profile — founders, executives, HQ, industry, employee count, and more. No parsing needed.
```json theme={null}
{
"properties": {
"id": {
"value": "c6772802-bdbc-4778-91e9-cd3d27d008d5",
"sources": []
},
"name": {
"value": "APPLE INC",
"sources": [
{
"name": "SEC",
"document": {
"endpoint": "https://efts.sec.gov/LATEST/search-index?q=%22APPLE+INC%22",
"params": {},
"response_hash": "3f0354a291ad77088d55bd2577294a85d5ba3c1b9ae0aa5a58c53bb24ed49111"
},
"date": "2026-02-26"
}
]
},
"aliases": {
"value": [
"Apple Computer, Inc."
],
"sources": []
},
"registered_address": {
"value": "C/O C T Corporation System, 330 N. Brand Blvd, Suite 700, Glendale, US-CA, 91203, US",
"sources": [
{
"name": "GLEIF",
"document": {
"endpoint": "https://api.gleif.org/api/v1/lei-records?filter%5Bentity.legalName%5D=APPLE+INC&page%5Bsize%5D=20",
"params": {},
"response_hash": "7089723cc94015908b284e2637d34fca0d700bccca36b0f83e4fb6e93c211437"
},
"date": "2026-02-26"
}
]
},
"headquarters_address": {
"value": "One Apple Park Way, Cupertino, US-CA, 95014, US",
"sources": [
{
"name": "GLEIF",
"document": {
"endpoint": "https://api.gleif.org/api/v1/lei-records?filter%5Bentity.legalName%5D=APPLE+INC&page%5Bsize%5D=20",
"params": {},
"response_hash": "7089723cc94015908b284e2637d34fca0d700bccca36b0f83e4fb6e93c211437"
},
"date": "2026-02-26"
}
]
},
"cik": {
"value": "0000320193",
"sources": [
{
"name": "SEC",
"document": {
"endpoint": "https://efts.sec.gov/LATEST/search-index?q=%22APPLE+INC%22",
"params": {},
"response_hash": "3f0354a291ad77088d55bd2577294a85d5ba3c1b9ae0aa5a58c53bb24ed49111"
},
"date": "2026-02-26"
}
]
},
"lei": {
"value": "HWUPKR0MPOU8FGXBT394",
"sources": [
{
"name": "GLEIF",
"document": {
"endpoint": "https://api.gleif.org/api/v1/lei-records?filter%5Bentity.legalName%5D=APPLE+INC&page%5Bsize%5D=20",
"params": {},
"response_hash": "7089723cc94015908b284e2637d34fca0d700bccca36b0f83e4fb6e93c211437"
},
"date": "2026-02-26"
}
]
},
"bics": {
"value": [
"APLEUS66XXX"
],
"sources": []
},
"legal_name": {
"value": "Apple Inc.",
"sources": [
{
"name": "GLEIF",
"document": {
"endpoint": "https://api.gleif.org/api/v1/lei-records?filter%5Bentity.legalName%5D=APPLE+INC&page%5Bsize%5D=20",
"params": {},
"response_hash": "7089723cc94015908b284e2637d34fca0d700bccca36b0f83e4fb6e93c211437"
},
"date": "2026-02-26"
}
]
}
},
"relationships": {
"outgoing": {},
"incoming": {}
},
"numerical_observations": []
}
```
Use `entity_search` to look up any entity by name (for example "Apple")
```json theme={null}
{
"entities": [
{"id": "c6772802-bdbc-4778-91e9-cd3d27d008d5", "name": "APPLE INC", "entity_type": "Company", "description": "Founded in 1976, this Cupertino‑based firm with 164,000 employees is the direct parent of Apple Operations India, Apple Canada, and others, and current CEO is Tim Cook."},
{"id": "ccee8487-8170-4ee7-81d5-cb1f9a7dc1a7", "name": "Apple Intelligence", "entity_type": "Product", "description": null},
{"id": "051a574e-cac7-4ff1-bb1a-20ef410b2a0b", "name": "Apple Korea Limited", "entity_type": "Company", "description": "A Korean subsidiary of Apple Inc."},
{"id": "4dce2f0b-87b3-4a9a-b70f-6f14e67f463b", "name": "APPLE CANADA INC.", "entity_type": "Company", "description": "A Canadian company located at 120 Bremner Boulevard, Toronto, that operates as a subsidiary of Apple Inc."}
]
}
```
Fuzzy matching included — searching "Apple" also returns related products, subsidiaries, and legal entities.
# Search Entities
Source: https://docs.cala.ai/features/search-entities
Search for any entity by name: companies, people, products, places, laws, and more. Fuzzy matching included.
* Allows searching and filtering entities by various criteria
* Returns a list of matching entities with their ID, type, and a short description
* Helps agents find relevant entities in the Cala's Knowledge
## Example:
```json theme={null}
{"name":"Tesla"}
```
Returns all matching entities across types — companies, people, products, facilities, and more. Each result includes an `id`, `name`, `entity_type`, and a `description` when available (`null` if not).
```json theme={null}
{
"entities": [
{"id": "2f3cb1a7-b8b8-4ef8-a3ae-b5b274d5601d", "name": "Tesla Motors, Inc.", "entity_type": "Company", "description": "A multinational automotive manufacturer and software, hardware, and financial services provider based in Austin, Texas, with over 130,000 employees."},
{"id": "8d6e0b83-7cf0-4fbf-a6f0-653df0c7ee9d", "name": "Tesla Semi", "entity_type": "Product", "description": null},
{"id": "5cfa93b1-008e-41ab-8a20-dc112e7fec17", "name": "Nikola Tesla", "entity_type": "Person", "description": "A Serbian who founded Tesla Electric Company."},
{"id": "f1c4a574-3e14-4d3c-8f8d-95e6d747670f", "name": "1 Tesla Road", "entity_type": "Facility", "description": null},
{"id": "6f9eebde-824f-49b2-8a89-6de8c419fba8", "name": "Tesoro", "entity_type": "Company", "description": "A logistics firm registered in Wilmington, Delaware and headquartered at Ridgewood Parkway in San Antonio, Texas."}
]
}
```
One search for "Tesla" returns the company, its products, a historical person, and even a facility — all typed and ready to explore.
Narrow results to specific types using the `entity_types` parameter:
```json theme={null}
{"name":"Tesla", "entity_types":"Person"}
```
```json theme={null}
{
"entities": [
{"id": "5cfa93b1-008e-41ab-8a20-dc112e7fec17", "name": "Nikola Tesla", "entity_type": "Person", "description": "A Serbian who founded Tesla Electric Company."}
]
}
```
Available entity types:
| Type | Description | Examples |
| ------------------------ | ------------------------------------------------- | ----------------------------------- |
| `GPE` | Geopolitical entities (countries, cities, states) | Spain, San Francisco, Texas |
| `Company` | Companies & corporations | Tesla, OpenAI, Y Combinator |
| `CorporateEvent` | Corporate events | Tesla Q4 2024 Earnings Call |
| `Country` | Sovereign countries | United States, Japan, Brazil |
| `CountryRegion` | Regions within countries | California, Bavaria, Tuscany |
| `EducationalInstitution` | Universities & schools | MIT, Stanford University |
| `Facility` | Facilities & buildings | 1 Tesla Road, Pentagon |
| `Industry` | Industries & sectors | Automotive, Artificial Intelligence |
| `Language` | Languages | English, Mandarin |
| `Law` | Laws & regulations | GDPR, Securities Act of 1933 |
| `Location` | Regions & geographic areas | Southern Europe, Sahara Desert |
| `Organization` | Non-company organizations | United Nations, NATO, FIFA |
| `Person` | People | Nikola Tesla, Sam Altman |
| `Product` | Products & services | Tesla Semi, GPT-4o |
| `WorkOfArt` | Creative works | The Great Gatsby, Starry Night |
You can pass multiple types: `entity_types=Company&entity_types=Person`
| Parameter | Type | Required | Description |
| -------------- | ------- | -------- | ------------------------------- |
| `name` | string | Yes | Entity name to search for |
| `entity_types` | array | No | Filter by entity type(s) |
| `limit` | integer | No | Max results (1–100, default 20) |
```bash theme={null}
# Get up to 5 Company results for "Tesla"
curl "https://api.cala.ai/v1/entities?name=Tesla&entity_types=Company&limit=5" \
-H "X-API-KEY: YOUR_CALA_API_KEY"
```
Use the returned entity UUIDs with `POST /v1/entities/{entity_id}` to get full profiles — founders, executives, funding, HQ, and more.
# Structured Answer
Source: https://docs.cala.ai/features/structured-answer
Returns **a tabular JSON rows plus matching entities** from Cala's knowledge base. Use `knowledge_query` (`POST /v1/knowledge/query`) when you need structured data ready for programmatic use rather than a natural-language answer.
Input can be a **Cala QL expression** or a **natural-language question** — both produce the same structured response shape.
* Navigate relationships between entities using dot notation
* Filter results by applying conditions directly in the path
* Access nested attributes across multiple entity relationships
* Get structured, typed responses ready for your applications
## Query language syntax
Build queries using dot notation and operators. This syntax works on both `knowledge_query` and `knowledge_search`.
| Operator | Meaning | Example |
| :------- | :------------------------------------------- | :------------------------ |
| `.` | Navigate relationships and access properties | `OpenAI.founded.year` |
| `=` | Filter by Exact match | `startups.location=Spain` |
| `!=` | Exclude | `startups.location!=US` |
| `>` | Greater than | `startups.funding>10M` |
| `<` | Less than | `startups.funding<50M` |
| `>=` | Greater than or equal | `startups.funding>=50M` |
| `<=` | Less than or equal | `startups.funding<=50M` |
Chain filters with dots: `startups.location=Spain.funding>10M.funding<50M`
## Example
Startups in Spain with funding between €10M and €50M:
```json theme={null}
{"input": "startups.location=Spain.funding>10M.funding<50M"}
```
Every response includes two parts:
Typed, filterable data — not paragraphs of text. Each result is a structured object with consistent fields.
```json theme={null}
{
"results": [
{
"company": "Amenitiz",
"sector": "Hospitality SaaS",
"funding_amount": "€38.9M",
"round_type": "Series B",
"year": 2025
},
{
"company": "H2SITE",
"sector": "Hydrogen Energy",
"funding_amount": "€36M ($37.2M)",
"round_type": "Series B",
"year": 2025
},
{
"company": "Fracttal",
"sector": "AI Maintenance",
"funding_amount": "€29.8M ($35M)",
"round_type": "Series B",
"year": 2026
},
{
"company": "Heura",
"sector": "Plant-based Foods",
"funding_amount": "€40M",
"round_type": "Total (multiple rounds)",
"year": 2023
},
{
"company": "Housfy",
"sector": "Real Estate",
"funding_amount": "€30M",
"round_type": "Series B",
"year": 2022
},
{
"company": "Highlight Therapeutics",
"sector": "Biotech",
"funding_amount": "€37.6M",
"round_type": "Venture Round",
"year": 2024
},
{
"company": "011h",
"sector": "Construction Tech",
"funding_amount": "€40.4M",
"round_type": "Venture Round",
"year": 2024
},
{
"company": "Kreios Space",
"sector": "Satellite Tech",
"funding_amount": "€10.6M",
"round_type": "Seed",
"year": 2025
},
{
"company": "Internxt",
"sector": "Security/Storage",
"funding_amount": "€10.9M",
"round_type": "Seed",
"year": 2020
},
{
"company": "Nomad Solar Energy",
"sector": "Solar Energy",
"funding_amount": "€15M",
"round_type": null,
"year": null
},
{
"company": "Universal DX",
"sector": "Healthcare",
"funding_amount": "€20M",
"round_type": null,
"year": null
},
{
"company": "Maisa AI",
"sector": "AI",
"funding_amount": "€30M",
"round_type": null,
"year": null
},
{
"company": "Reveni",
"sector": null,
"funding_amount": "€17.3M",
"round_type": null,
"year": null
}
]
}
```
13 startups returned — each with company name, sector, funding amount, round type, and year. This is structured data, not text to parse.
Every company in the results is automatically linked to a Cala entity with a unique UUID and type.
```json theme={null}
{
"entities": [
{"id": "e2ce8098-dea6-4fdd-b226-c33923b5efe1", "name": "Amenitiz", "entity_type": "Company"},
{"id": "b2171d05-18d4-4b1b-8953-208ce66be8d6", "name": "H2SITE", "entity_type": "Company"},
{"id": "714be9ad-cce1-46e5-b0d5-a01f71f26d01", "name": "Fracttal", "entity_type": "Company"},
{"id": "3d47d7b1-8f83-4be3-be42-b9d8712c1d4c", "name": "Heura", "entity_type": "Company"},
{"id": "3349e982-694e-4923-9af7-480af3efcedc", "name": "Housfy", "entity_type": "Company"},
{"id": "b5c7a256-79b6-43d9-84fb-24c4403cc098", "name": "Highlight Therapeutics", "entity_type": "Company"},
{"id": "63a254cb-40bc-49a2-9922-7ae806398c38", "name": "011h", "entity_type": "Company"},
{"id": "73f3603f-624e-457a-b5ad-f192792cc15b", "name": "Kreios Space", "entity_type": "Company"},
{"id": "9beb50ad-d4dc-4ef8-bd59-7a26bbcbb413", "name": "Internxt", "entity_type": "Company"},
{"id": "877fc47b-b23a-4cc9-b929-50d2a629fd38", "name": "Nomad Solar Energy", "entity_type": "Company"},
{"id": "fd163be0-ab87-4218-b0a6-48a5cc46c711", "name": "Universal DX", "entity_type": "Company"},
{"id": "42285452-6100-473b-a8bb-85c731e3e1e5", "name": "Maisa AI", "entity_type": "Company"},
{"id": "ff47dfd6-97de-401a-82ae-edc3adf35694", "name": "Reveni", "entity_type": "Company"}
]
}
```
Use any entity UUID to get the full profile: `POST /v1/entities/e2ce8098-dea6-4fdd-b226-c33923b5efe1` returns everything Cala knows about Amenitiz — founders, executives, HQ, employee count, and more.
## Natural-language input also works
You can also send a plain question — the response is still structured rows, not prose:
```json theme={null}
{"input": "What are the most promising climate tech startups in Southern Europe?"}
```
## More query examples
These use the Cala QL syntax. Natural-language questions also work with this endpoint.
```json theme={null}
{"input": "OpenAI.founded.year"}
{"input": "ibex35.companies.employee_count>2000"}
{"input": "companies.founder.incorporation>2020.previous_job=Google"}
```
# About Cala
Source: https://docs.cala.ai/index
Cala turns internet chaos into **structured, verified knowledge** that AI agents and LLMs can call as a tool.
Building agentic products means relying on external information, but agents work best with verified, structured, typed data they can call deterministically, not the open web. Cala abstracts away ingestion, normalization, and verification behind a simple API, so you can ship agentic products faster without building brittle data pipelines.
## Why Cala
Web search APIs crawl the open web and return URLs, scraped text, and HTML fragments. Your agent then has to parse, deduplicate, and hope the data is accurate.
Cala is different. It's a **verified entity graph** made of typed entities with structured fields, deterministic queries, and full traceability back to source. Every query returns clean, typed data your agent can reason over immediately.
Web search returns:\
"Here are 10 links about Spanish startups. Good luck parsing them."
Cala returns:
```json theme={null}
[
{ "name": "Luzia", "funding": "13M", "location": "Spain" },
{ "name": "Nomad Solar", "funding": "15M", "location": "Spain" },
{ "name": "Embat", "funding": "21.5M", "location": "Spain" },
...
]
```
## Key capabilities
* **Natural-language answers**: Get succinct, token-optimized answers in markdown — with full source citations and explainability
* **Structured answers**: Get typed, tabular JSON rows ready for programmatic use
* **Flexible input**: Both endpoints accept natural-language questions **and** Cala's query language (dot-notation filters like `OpenAI.founded.year` → `2015`) — the input format is interchangeable; only the output differs
* **Entity discovery**: Find and explore entities across companies, people, products, research papers, laws, places and more
* **Full traceability** — Every answer links back to its source documents, all verified and fact-checked
* **MCP integration** — Connect directly to Cursor, Claude Desktop, VS Code, and any MCP-compatible agent
## Tool Selection Cheat Sheet
| I want to... | Use | Endpoint |
| :------------------------------------------------------------ | :----------------- | -------------------------- |
| Get a succinct, sourced answer in natural language (markdown) | `knowledge_search` | `/v1/knowledge/search` |
| Get a structured, tabular answer (typed JSON rows) | `knowledge_query` | `/v1/knowledge/query` |
| Look up an entity by name | `entity_search` | `/v1/entities` |
| Retrieve full details for a known entity UUID | `retrieve_entity` | `/v1/entities/{entity_ID}` |
Both `knowledge_search` and `knowledge_query` accept either a natural-language question or a Cala QL expression as input. The only difference is the output format.
## Get started
Get your first results with Cala
Learn more about the Cala API
# Agent Skill
Source: https://docs.cala.ai/integrations/agent-skill
Give your agent the knowledge it needs to use Cala well.
The Cala agent skill is a `SKILL.md` file that tells your agent what Cala is, when to use it, which tool to call, and how to handle edge cases — without you having to prompt-engineer any of it.
Install it once. It works across Claude Code, Cursor, Copilot, Amp, Codex, and any other agent that supports the [Agent Skills](https://agentskills.io) format.
## Install
```bash theme={null}
npx skills add cala-ai/cala-skill
```
Or download [`SKILL.md`](https://raw.githubusercontent.com/cala-ai/cala-skill/main/SKILL.md) and place it in your agent's skill directory manually.
## Use with MCP
The skill and the MCP server are complementary. The skill gives your agent the instructions — the MCP server gives it the live connection to execute queries. For the best results, use both.
Connect your agent to Cala's live query tools.
# MCP
Source: https://docs.cala.ai/integrations/mcp
Connect your AI agent to Cala's MCP
```json theme={null}
https://api.cala.ai/mcp/
```
For more information about MCP and how it works, you can read more about it [here](https://modelcontextprotocol.io/docs/getting-started/intro).
**Pair with the agent skill.** The MCP server gives your agent access to Cala's tools. The [agent skill](/integrations/agent-skill) gives it the knowledge to use them well. Install both for the full experience.
## Connect your agent to Cala's MCP
You can use Cala via our MCP. To get started, you need to get an API key to authenticate your MCP client. Go to our [Console](https://console.cala.ai/api-keys) and create a new API key.
Create a free Cala account and get your API key.
With your API key in hand, you can connect your AI agent such as Cursor, Claude Code and others to our MCP server. Cala MCP gives AI agents access to verified, structured and typed knowledge — both as natural-language answers and structured data — as well as entity information.
Add to `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"Cala": {
"url": "https://api.cala.ai/mcp/",
"headers": {
"X-API-KEY": "YOUR_CALA_API_KEY"
}
}
}
}
```
For more information, follow their documentation [here](https://cursor.com/docs/context/mcp#installing-mcp-servers).
Add to `.vscode/mcp.json`:
```json theme={null}
{
"servers": {
"Cala": {
"type": "http",
"url": "https://api.cala.ai/mcp/",
"headers": {
"X-API-KEY": "YOUR_CALA_API_KEY"
}
}
}
}
```
For more information, follow their documentation [here](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
For Claude Desktop you don't need to have an API key as authentication is done via OAuth.
You can configure Cala MCP in Claude Desktop from the Connectors UI.
#### Individual account
Go to **Customize → Connectors**, click `+`, and select **Add custom connector**.
Enter the following information:
* Name: Cala
* URL: `https://api.cala.ai/mcp/`
And in **Advanced settings**:
* Client ID: `sZasi0PYnHtNtiPBSFBAro5XYzZrVl8Q`
* Client Secret: leave empty
A sign-in pop-up will appear — log in with your Cala credentials to authenticate. Once connected, toggle on the tools you want to make available to Claude.
#### Organization account (Team or Enterprise)
An Owner or Primary Owner can go to **Organization settings → Connectors**, click **Add**.
Enter the following information:
* Name: Cala
* URL: `https://api.cala.ai/mcp/`
And in **Advanced settings**:
* Client ID: `sZasi0PYnHtNtiPBSFBAro5XYzZrVl8Q`
* Client Secret: leave empty
If you are not an admin, ask your administrator to complete this step.
Go to **Customize → Connectors**, find Cala (labeled **Custom**), and click **Connect**.
A sign-in pop-up will appear — log in with your Cala credentials to authenticate. Once connected, toggle on the tools you want to make available to Claude.
Run the following command in your terminal adding your API key:
```
claude mcp add --transport http cala https://api.cala.ai/mcp/ --header "X-API-KEY: YOUR_CALA_API_KEY"
```
Add to `~/.vibe/config.json`:
```json theme={null}
{
"mcpServers": {
"Cala": {
"url": "https://api.cala.ai/mcp",
"headers": {
"X-API-KEY": "YOUR_CALA_API_KEY"
}
}
}
}
```
Add to `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.cala]
enabled = true
command = "npx"
args = [
"-y",
"mcp-remote",
"https://api.cala.ai/mcp",
"--header",
"X-API-Key:${CALA_API_KEY}"
]
[mcp_servers.cala.env]
CALA_API_KEY = "YOUR_CALA_API_KEY"
```
To support the full power of our graph's flexible schema, this MCP server utilizes dynamic JSON objects. This provides a "schema-less" experience for the LLM. Because of this, it is incompatible with OpenAI's "strict mode" so please ensure `strict: false` is set in your OpenAI specification.
For more information, follow their documentation [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp)
For clients with built-in remote MCP support:
```json theme={null}
{
"mcpServers": {
"Cala": {
"url": "https://api.cala.ai/mcp/",
"headers": {
"X-API-KEY": "YOUR_CALA_API_KEY"
}
}
}
}
```
For clients without built-in remote MCP support:
```json theme={null}
{
"mcpServers": {
"Cala": {
"command": "npx",
"args": [
"mcp-remote",
"https://api.cala.ai/mcp/",
"--header",
"X-API-KEY: YOUR_CALA_API_KEY"
]
}
},
}
```
## Available Tools
Here are the tools available to the Cala MCP:
Get a succinct, token-optimized answer in natural-language markdown, with sources, explainability, and matching entities. Accepts either a natural-language question or a Cala QL expression as input.
Get verified knowledge as structured, typed JSON rows plus matching entities. Accepts either a Cala QL expression or a natural-language question as input.
Search entities by name with fuzzy matching.
Get the field schema for an entity by its UUID. Returns the available properties, relationships, and numerical observations you can use when querying an entity.
Retrieve information about an entity by its UUID.
## Hubs & Marketplaces
You can also find Cala's MCP server listed on the following hubs and marketplaces:
Browse Cala's MCP server listing on mcpservers.org.
Browse Cala's MCP server listing on mcp.so.
# n8n
Source: https://docs.cala.ai/integrations/n8n
Use Cala in your n8n workflows
Cala is a verified [n8n](https://n8n.io) community node. Give your n8n workflows access to verified, structured knowledge — with source citations, typed data, and entity resolution — without scraping or parsing.
## Get an API key
To authenticate the Cala node you need an API key from the Cala Console.
Create a free Cala account and get your API key.
## Install the Cala node
View the Cala node on the n8n integrations marketplace.
1. Sign in to [n8n](https://app.n8n.cloud/register) and open the workflow editor.
2. Click **+** to open the Nodes panel and search for **Cala**.
3. Add the node, then paste your API key in the credentials dialog.
## Available operations
Get a sourced, natural-language answer to a question. Maps to Cala's knowledge\_search endpoint.
Get structured, typed JSON rows from a Cala QL expression or natural-language question. Maps to Cala's knowledge\_query endpoint.
Find entities by name with fuzzy matching.
Get available properties, relationships, and numerical observations for an entity.
Retrieve the full profile of an entity by its UUID.
# Quickstart
Source: https://docs.cala.ai/quickstart
Start using Cala in 30 seconds.
**Using an AI assistant?** Install the Cala skill and your agent will know how to use Cala out of the box — no extra prompting needed.
```bash theme={null}
npx skills add cala-ai/cala-skill
```
[Learn more](/integrations/agent-skill)
## Create your API key
Get an API key to authenticate your requests. Go to our [Console](https://console.cala.ai/api-keys) and create a new API key.
Create a free Cala account and get your API key.
## Make your first request
Both endpoints accept the same input — the difference is how they respond. Send a Cala QL expression (or a natural-language question) and choose the output shape you need.
```python Structured Answer (knowledge_query) icon=python theme={null}
import requests
url = "https://api.cala.ai/v1/knowledge/query"
query = "startups.location=Spain.funding>10M.funding<50M"
payload = { "input": query }
headers = {
"X-API-KEY": "YOUR_API_KEY",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
```javascript Natural Language Answer (knowledge_search) icon=square-js theme={null}
const options = {
method: 'POST',
headers: {'X-API-KEY': 'YOUR_API_KEY', 'Content-Type': 'application/json'},
body: JSON.stringify({input: 'startups.location=Spain.funding>10M.funding<50M'})
};
fetch('https://api.cala.ai/v1/knowledge/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
```
Same input, two output shapes.
## Get a Structured Answer
`POST /v1/knowledge/query` returns JSON rows — ready for programmatic use.
```json theme={null}
[
{ "name": "Luzia", "funding": "13M", "location": "Spain" },
{ "name": "Nomad Solar", "funding": "15M", "location": "Spain" },
{ "name": "Embat", "funding": "21.5M", "location": "Spain" },
{ "name": "Matteco", "funding": "16M+", "location": "Spain" },
{ "name": "Exoticca", "funding": "25.2M", "location": "Spain" },
{ "name": "Multiverse Computing", "funding": "12.5M", "location": "Spain" }
]
```
## Get a Natural-Language Answer
`POST /v1/knowledge/search` returns a succinct, sourced answer in markdown.
```markdown theme={null}
## Spanish Startups (€10M–€50M funding)
**Luzia** — AI assistant, €13M raised.
**Nomad Solar** — Solar energy, €15M raised.
**Embat** — Treasury management, €21.5M raised.
**Matteco** — Green hydrogen materials, €16M+ raised.
**Exoticca** — Travel tech, €25.2M raised.
**Multiverse Computing** — Quantum computing, €12.5M raised.
```
No parsing. No deduplication. No hallucinated data. Verified, sourced, deterministic.
## Next steps
That's it! You can now start using Cala to build your own applications. Deep dive into the available endpoints, params and responses in our [API Reference](/api-reference/query) section.