### Example Structured API Response

Source: https://docs.cala.ai/quickstart

An example of the JSON response format returned by the Cala API when querying for startup information.

```json
[
  { "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" }
]
```

--------------------------------

### JSON Query Examples for Data Retrieval

Source: https://docs.cala.ai/features/knowledge-query

These examples demonstrate how to query data using JSON objects. They cover retrieving specific information like founding years, filtering companies by employee count, and complex queries involving incorporation dates and previous employment.

```json
{"input": "OpenAI.founded.year"}
```

```json
{"input": "ibex35.companies.employee_count>2000"}
```

```json
{"input": "companies.founder.incorporation>2020.previous_job=Google"}
```

--------------------------------

### POST /v1/knowledge/query

Source: https://docs.cala.ai/quickstart

Executes a structured query against the Cala knowledge base to retrieve specific data points.

```APIDOC
## POST /v1/knowledge/query

### Description
Queries the knowledge base using a structured string format to filter and retrieve entities.

### Method
POST

### Endpoint
https://api.cala.ai/v1/knowledge/query

### Parameters
#### Request Body
- **input** (string) - Required - The query string defining filter criteria (e.g., "startups.location=Spain.funding>10M")

### Request Example
{
  "input": "startups.location=Spain.funding>10M.funding<50M"
}

### Response
#### Success Response (200)
- **data** (array) - A list of objects matching the query criteria.

#### Response Example
[
  { "name": "Luzia", "funding": "13M", "location": "Spain" },
  { "name": "Embat", "funding": "21.5M", "location": "Spain" }
]
```

--------------------------------

### POST /v1/knowledge/search

Source: https://docs.cala.ai/quickstart

Performs a search operation against the knowledge base to retrieve relevant information based on input strings.

```APIDOC
## POST /v1/knowledge/search

### Description
Searches the knowledge base for information matching the provided input criteria.

### Method
POST

### Endpoint
https://api.cala.ai/v1/knowledge/search

### Parameters
#### Request Body
- **input** (string) - Required - The search query string.

### Request Example
{
  "input": "<search_query>"
}

### Response
#### Success Response (200)
- **results** (array) - A list of search results.

#### Response Example
{
  "results": []
}
```

--------------------------------

### Perform Knowledge Query with Cala API

Source: https://docs.cala.ai/quickstart

Demonstrates how to authenticate and send a POST request to the Cala knowledge query endpoint. It requires an API key and accepts a query string to retrieve structured data.

```python
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
const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({input: '<string>'})
};

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

--------------------------------

### GET /query

Source: https://docs.cala.ai/features/knowledge-query

Executes a structured query against the knowledge base using dot-notation syntax and conditional operators.

```APIDOC
## GET /query

### Description
Retrieves precise and typed data from the knowledge base by navigating entity relationships and applying filters.

### Method
GET

### Endpoint
/query

### Parameters
#### Query Parameters
- **q** (string) - Required - The query string using dot notation (e.g., "startups.location=Spain.funding>10M")

### Request Example
GET /query?q=startups.location=Spain.funding>10M

### Response
#### Success Response (200)
- **data** (object) - The structured, typed response containing the requested entity attributes.

#### Response Example
{
  "data": [
    {
      "name": "Example Startup",
      "location": "Spain",
      "funding": "15M"
    }
  ]
}
```

--------------------------------

### Execute API Request with cURL

Source: https://docs.cala.ai/features/search-entities

Provides a bash example for querying the Cala AI API using cURL. It includes parameters for name, entity filtering, and result limiting, along with the required API key header.

```bash
# 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"
```

--------------------------------

### Entity Search Example (JSON)

Source: https://docs.cala.ai/features/retrieve-entity

Demonstrates the use of entity_search to find entities by name. The input is a search query, and the output is a JSON object containing a list of matching entities, each with an ID, name, and entity type. Fuzzy matching is enabled, so searching for 'Apple' also returns related entities.

```json
{
  "entities": [
    {"id": "c6772802-bdbc-4778-91e9-cd3d27d008d5", "name": "APPLE INC", "entity_type": "Company"},
    {"id": "ccee8487-8170-4ee7-81d5-cb1f9a7dc1a7", "name": "Apple Intelligence", "entity_type": "Product"},
    {"id": "051a574e-cac7-4ff1-bb1a-20ef410b2a0b", "name": "Apple Korea Limited", "entity_type": "Company"},
    {"id": "4dce2f0b-87b3-4a9a-b70f-6f14e67f463b", "name": "APPLE CANADA INC.", "entity_type": "Company"}
  ]
}
```

--------------------------------

### Retrieve Full Entity Profile via POST Request

Source: https://docs.cala.ai/features/retrieve-entity

This example demonstrates how to retrieve a complete, structured profile for an entity using a POST request to the /entities endpoint. The response includes detailed information such as founders, executives, HQ, industry, and employee count, requiring no further parsing.

```json
{
    "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": []
}
```

--------------------------------

### Example JSON Response from Cala

Source: https://docs.cala.ai/index

This JSON snippet demonstrates the structured output format provided by Cala for entities, including fields like name, funding, and location. This data is directly usable by AI agents.

```json
[
  { "name": "Luzia", "funding": "13M", "location": "Spain" },
  { "name": "Nomad Solar", "funding": "15M", "location": "Spain" },
  { "name": "Embat", "funding": "21.5M", "location": "Spain" }
... 
]
```

--------------------------------

### GET /v1/entities

Source: https://docs.cala.ai/api-reference/search-entities

Search for entities by name using fuzzy matching and optional type filters.

```APIDOC
## GET /v1/entities

### Description
Find entities by name with fuzzy matching. Optionally filter by specific entity types to narrow down results.

### Method
GET

### Endpoint
/v1/entities

### Parameters
#### Query Parameters
- **name** (string) - Required - The name or partial name of the entity to search for.
- **entity_types** (array) - Optional - A list of entity types to filter by (e.g., Person, GPE, Location).
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
GET /v1/entities?name=Berlin&entity_types=GPE&limit=5

### Response
#### Success Response (200)
- **entities** (array) - A list of matching entity objects containing IDs and basic information.

#### Response Example
{
  "entities": [
    {
      "id": "ent_123",
      "name": "Berlin",
      "type": "GPE"
    }
  ]
}
```

--------------------------------

### GET /v1/entities

Source: https://docs.cala.ai/api-reference/search-entities

Search for entities by name with optional type filtering and result limiting.

```APIDOC
## GET /v1/entities

### Description
Find entities by name using fuzzy matching. Optionally filter by entity type and limit the number of results returned.

### Method
GET

### Endpoint
https://api.cala.ai/v1/entities

### Parameters
#### Query Parameters
- **name** (string) - Required - Entity name to search for.
- **entity_types** (array) - Optional - Filter by entity types (e.g., Person, Company, Location).
- **limit** (integer) - Optional - Maximum number of results (1-100, default 20).

### Request Example
GET /v1/entities?name=OpenAI&limit=5

### Response
#### Success Response (200)
- **entities** (array) - List of entities matching the search query, ordered by relevance.

#### Response Example
{
  "entities": [
    {
      "entity_type": "Company",
      "id": "e5bb591a-d308-4aa5-9672-96046d366cde",
      "name": "OpenAI"
    }
  ]
}
```

--------------------------------

### Get Entity Profile

Source: https://docs.cala.ai/api-reference/entities

Fetches the complete profile of an entity given its UUID. This includes legal name, industry, founders, executives, headquarters, employee count, and more.

```APIDOC
## GET /entities/{entity_id}

### Description
Get the full profile of an entity by its UUID. Returns detailed information including legal name, industry, founders, executives, headquarters, employee count, and more.

### Method
GET

### Endpoint
/entities/{entity_id}

### Parameters
#### Path Parameters
- **entity_id** (string) - Required - The unique identifier (UUID) of the entity.

### Request Example
(No request body for GET requests, parameters are in the path)

### Response
#### Success Response (200)
- **entity_id** (string) - The unique identifier of the entity.
- **legal_name** (string) - The legal name of the entity.
- **industry** (string) - The industry the entity operates in.
- **founders** (array) - A list of the entity's founders.
- **executives** (array) - A list of the entity's executives.
- **headquarters** (string) - The location of the entity's headquarters.
- **employee_count** (integer) - The number of employees at the entity.

#### Response Example
```json
{
  "entity_id": "0dcb275d-e614-4760-a1a0-fa8d989e2766",
  "legal_name": "Example Corp",
  "industry": "Technology",
  "founders": ["Jane Doe"],
  "executives": ["John Smith"],
  "headquarters": "San Francisco, CA",
  "employee_count": 500
}
```
```

--------------------------------

### GET /entities/{id}

Source: https://docs.cala.ai/api-reference/entities

Retrieves the full profile of a specific entity using its unique identifier.

```APIDOC
## GET /entities/{id}

### Description
Retrieves the full profile of a specific entity using its unique identifier.

### Method
GET

### Endpoint
/entities/{id}

#### Path Parameters
- **id** (string) - Required - The unique identifier of the entity.

### Response
#### Success Response (200)
- **id** (string) - The ID of the entity.
- **name** (string) - The name of the entity.
- **entity_type** (string) - The type of the entity. Enum: Entity, GPE, Company, CorporateEvent, Country, CountryRegion, EducationalInstitution, Facility, FinancialMetric, Industry, Language, Law, Location, Organization, Person, Product, WorkOfArt.
- **properties** (object) - List of property names available for this entity (e.g. id, name, currency).
- **relationships** (object) - Outgoing and incoming relationship types.
- **numerical_observations** (array) - Numerical observations keyed by observation type.

#### Response Example
```json
{
  "entity_type": "Company",
  "id": "9af54183-a1c6-468c-b608-e96ddb80366d",
  "name": "Apple Inc",
  "numerical_observations": [],
  "properties": {
    "name": {
      "sources": [
        {
          "date": "2026-02-26",
          "document": {
            "endpoint": "https://efts.sec.gov/LATEST/search-index?q=%5C%22APPLE+INC%5C%22",
            "params": {},
            "response_hash": "3f0354a291ad77088d55bd2577294a85d5ba3c1b9ae0aa5a58c53bb24ed49111"
          },
          "name": "SEC"
        }
      ],
      "value": "APPLE INC"
    },
    "aliases": {
      "sources": [],
      "value": [
        "Apple Computer, Inc."
      ]
    },
    "registered_address": {
      "sources": [
        {
          "date": "2026-02-26",
          "document": {
            "endpoint": "https://api.gleif.org/api/v1/lei-records?filter%5Bentity.legalName%5D=APPLE+INC&page%5Bsize%5D=20",
            "params": {},
            "response_hash": "7089723cc94015908b284e2637d34fca0d700bccca36b0f83e4fb6e93c211437"
          },
          "name": "GLEIF"
        }
      ],
      "value": "C/O C T Corporation System, 330 N. Brand Blvd, Suite 700, Glendale, US-CA, 91203, US"
    },
    "employee_count": {
      "sources": [
        {
          "date": "2026-03-01",
          "document": "https://www.macrotrends.net/stocks/charts/AAPL/apple/number-of-employees",
          "name": "Macrotrends | The Long Term Perspective on Markets"
        }
      ],
      "value": 164000
    }
  },
  "relationships": {
    "incoming": {
      "IS_BOARD_MEMBER_OF": [
        {
          "entity_types": [
            "Person"
          ],
          "id": "7e01020c-cd58-468c-8b2b-d6d1de1ba7bd",
          "name": "Andrea Jung",
          "properties": {
            "target_id": "c6772802-bdbc-4778-91e9-cd3d27d008d5"
          }
        }
      ]
    }
  }
}
```
```

--------------------------------

### Cala API Tool Selection - Get Entity

Source: https://docs.cala.ai/index

This entry explains the 'get_entity' tool, which retrieves full details for a known entity UUID using the Cala API. The endpoint is '/v1/entities/{entity_ID}'.

```markdown
| I want to...                                               |
| :--------------------------------------------------------- | 
| Get full details for a known entity UUID                   |
| Use                | `get_entity` |
| Endpoint                   | `/v1/entities/{entity_ID}` |
```

--------------------------------

### Query Startups by Location and Funding (JSON)

Source: https://docs.cala.ai/features/knowledge-query

This snippet demonstrates how to query for startups in Spain with funding between €10M and €50M using structured path syntax. The input is a JSON object specifying the query criteria.

```json
{
  "input": "startups.location=Spain.funding>10M.funding<50M"
}
```

--------------------------------

### GET /entities/{uuid}/introspection

Source: https://docs.cala.ai/api-reference/entity-introspection

Retrieves the schema, available properties, and relationships for a specific entity identified by its UUID.

```APIDOC
## GET /entities/{uuid}/introspection

### Description
Fetches the field schema for an entity by its UUID. This endpoint returns the available properties, relationships, and numerical observations that can be used when querying the entity.

### Method
GET

### Endpoint
/entities/{uuid}/introspection

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the entity.

### Request Example
GET /entities/c6772802-bdbc-4778-91e9-cd3d27d008d5/introspection

### Response
#### Success Response (200)
- **properties** (array) - List of available attributes for the entity.
- **relationships** (array) - List of related entities or connections.
- **observations** (array) - List of numerical or metric-based observations.

#### Response Example
{
  "entity_id": "c6772802-bdbc-4778-91e9-cd3d27d008d5",
  "properties": ["name", "created_at", "status"],
  "relationships": ["owner", "parent_organization"],
  "observations": ["usage_count", "performance_score"]
}
```

--------------------------------

### Structured Startup Search Results (JSON)

Source: https://docs.cala.ai/features/knowledge-query

This JSON output represents the structured results of a startup search. It includes a list of companies, each with details such as company name, sector, funding amount, round type, and year. This format provides typed, filterable data.

```json
{
  "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
    }
  ]
}
```

--------------------------------

### GET /v1/entities/{entity_id}/introspection

Source: https://docs.cala.ai/api-reference/entity-introspection

Retrieves the field schema for a given entity by its numeric UUID. This endpoint returns available properties, relationships, and numerical observations that can be used when querying the entity.

```APIDOC
## GET /v1/entities/{entity_id}/introspection

### Description
Get the field schema for an entity by its numeric UUID. Returns the available properties, relationships,
and numerical observations you can use when querying the entity with `get_entity`.

### Method
GET

### Endpoint
/v1/entities/{entity_id}/introspection

### Parameters
#### Path Parameters
- **entity_id** (string) - Required - The numeric UUID of the entity.

### Request Example
```json
{
  "example": "GET /entities/c6772802-bdbc-4778-91e9-cd3d27d008d5/introspection"
}
```

### Response
#### Success Response (200)
- **properties** (array) - List of property names available for this entity (e.g. id, name, currency).
- **relationships** (object) - Outgoing and incoming relationship types.
- **numerical_observations** (object) - List of numerical observation names available for this entity.

#### Response Example
```json
{
  "numerical_observations": {
    "FinancialMetric": [
      {
        "cadence": "i",
        "description": "Amount of currency on hand as well as demand deposits with banks or financial institutions. Includes other kinds of accounts that have the general characteristics of demand deposits. Also includes short-term, highly liquid investments that are both readily convertible to known amounts of cash and so near their maturity that they present insignificant risk of changes in value because of changes in interest rates. Excludes cash and cash equivalents within disposal group and discontinued operation.",
        "id": "1d3eae40-0ba8-5baf-9907-6a4823b067bb",
        "name": "Cash and Cash Equivalents, at Carrying Value",
        "taxonomy": "us-gaap",
        "unit": "USD"
      }
    ]
  },
  "properties": [
    "cik",
    "headquarters_address",
    "lei",
    "registered_address",
    "founding_date",
    "esg_policy",
    "legal_name",
    "employee_count",
    "bics",
    "name",
    "aliases",
    "id"
  ],
  "relationships": {}
}
```
```

--------------------------------

### Search Entities via JSON

Source: https://docs.cala.ai/features/search-entities

Demonstrates the basic JSON structure for querying entities and the expected JSON response format containing a list of matched entities with their types and IDs.

```json
{"name":"Tesla"}
```

```json
{
  "entities": [
    {"id": "2f3cb1a7-b8b8-4ef8-a3ae-b5b274d5601d", "name": "Tesla Motors, Inc.", "entity_type": "Company"},
    {"id": "8d6e0b83-7cf0-4fbf-a6f0-653df0c7ee9d", "name": "Tesla Semi", "entity_type": "Product"}
  ]
}
```

--------------------------------

### POST /v1/knowledge/query

Source: https://docs.cala.ai/api-reference/query

Search verified knowledge using structured dot-notation query syntax for filtering entities by attributes.

```APIDOC
## POST /v1/knowledge/query

### Description
Search verified knowledge using structured dot-notation query syntax for filtering entities by attributes. This endpoint returns a structured array of matching results and identified entities.

### Method
POST

### Endpoint
https://api.cala.ai/v1/knowledge/query

### Parameters
#### Request Body
- **input** (string) - Required - The query string using dot-notation (e.g., "startups.location=Spain.funding>10M")

### Request Example
{
  "input": "startups.location=Spain.funding>10M.funding<50M"
}

### Response
#### Success Response (200)
- **results** (array) - A list of structured results matching the query.
- **entities** (array) - Entities identified in the answer.

#### Response Example
{
  "entities": [
    {
      "entity_type": "Company",
      "id": "e2932ee7-7b57-42b7-8c58-cdfcdf56ceb5",
      "name": "Amenitiz"
    }
  ],
  "results": [
    {
      "company": "Amenitiz",
      "funding_amount": "€38.9M",
      "sector": "Hospitality SaaS"
    }
  ]
}
```

--------------------------------

### POST /query

Source: https://docs.cala.ai/api-reference/query

Searches verified knowledge using structured dot-notation query syntax to filter entities by specific attributes.

```APIDOC
## POST /query

### Description
Searches verified knowledge using structured dot-notation query syntax. This endpoint returns a structured array of matching results and entities based on the provided attribute filters.

### Method
POST

### Endpoint
/query

### Parameters
#### Request Body
- **input** (string) - Required - The dot-notation query string (e.g., "startups.location=Spain.funding>10M")

### Request Example
{
  "input": "startups.location=Spain.funding>10M.funding<=50M"
}

### Response
#### Success Response (200)
- **results** (array) - A list of matching entities found based on the query criteria.

#### Response Example
{
  "results": [
    {
      "id": "startup_123",
      "name": "Example Startup",
      "location": "Spain",
      "funding": "25M"
    }
  ]
}
```

--------------------------------

### Query Knowledge using Structured Syntax (OpenAPI)

Source: https://docs.cala.ai/api-reference/query

This endpoint allows searching for verified knowledge using a structured dot-notation query syntax. It filters entities by attributes and returns a structured array of matching results and identified entities. The input field is 'input', not 'query'.

```yaml
openapi: 3.1.0
info:
  title: Cala AI
  summary: Verified, reliable knowledge one API call away
  description: >
    ### Knowledge Search
    Let's you search for verified knowledge to empower your AI Agent with the
    **right context**.
    ### Knowledge Entities
    Get information about entities, **structured** and reliable.
  version: Beta 1.0
servers:
  - url: https://api.cala.ai/
security: []
paths:
  /v1/knowledge/query:
    post:
      tags:
        - API v1
        - Knowledge
      summary: Query
      description: >-
        Search verified knowledge using structured dot-notation query syntax for
        filtering entities by attributes.
        Returns a structured array of matching results plus entities. The input
        field is called "input" (not "query").
        Examples:
        `{"input": "startups.location=Spain.funding>10M.funding<=50M"}`
        `{"input": "companies.industry=fintech.founded_year>=2020"}`
        `{"input": "people.role=CEO.company.industry=AI"}`
        Use this when: You need to filter/search entities by specific attributes
        (location, funding, industry, year, etc.).
        For free-text questions use `knowledge_search`. To look up a known
        entity by name use `entity_search`.
      operationId: knowledge_query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too many requests (rate limit exceeded)
          content:
            application/json:
              example:
                error: rate_limit_exceeded
                message: Rate limit per minute exceeded. Too many requests.
      security:
        - APIKeyHeader: []
components:
  schemas:
    QueryRequest:
      properties:
        input:
          type: string
          title: Input
          examples:
            - startups.location=Spain.funding>10M.funding<50M
      type: object
      required:
        - input
      title: QueryRequest
      example:
        input: startups.location=Spain.funding>10M.funding<50M
    QueryResponse:
      properties:
        results:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Results
          description: >-
            A list of structured results for the query. Shape and schema will be
            determined by the query.
          examples:
            - - 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:
          items:
            $ref: '#/components/schemas/EntityMention'
          type: array
          title: Entities
          description: Entities identified in the answer.
      type: object
      required:
        - results
        - entities
      title: QueryResponse
      description: Response in case of a successful structured query.
      example:
        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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'

```

--------------------------------

### APIKeyHeader Security Scheme

Source: https://docs.cala.ai/api-reference/query

Information about the API key authentication method using a header.

```APIDOC
## APIKeyHeader Security Scheme

### Description
This API uses header-based authentication with an API key.

### Type
API Key

### In
Header

### Name
X-API-KEY
```

--------------------------------

### POST /v1/entities/{id}

Source: https://docs.cala.ai/features/knowledge-search

Retrieves a full entity profile, including synthesized content, explainability, context, and related entities based on a unique UUID.

```APIDOC
## POST /v1/entities/{id}

### Description
Retrieves the full profile for a specific entity identified by its UUID. This endpoint provides synthesized information, reasoning chains, source provenance, and a list of associated entities.

### Method
POST

### Endpoint
/v1/entities/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique UUID of the entity (e.g., d6b818c0-1d2c-47ca-a7d3-5b5c35635769).

### Request Example
POST /v1/entities/d6b818c0-1d2c-47ca-a7d3-5b5c35635769

### Response
#### Success Response (200)
- **content** (string) - A synthesized markdown answer with structured sections.
- **explainability** (object) - Reasoning chain linking claims to specific source documents by UUID.
- **context** (array) - Source documents with full provenance (publisher, title, URL).
- **entities** (array) - List of mentioned entities with Cala UUIDs and types.

#### Response Example
{
  "content": "# Altano Energy\nAltano Energy is a key player in...",
  "explainability": { "chain": "..." },
  "context": [{ "publisher": "Example News", "title": "Energy Trends", "url": "http://example.com" }],
  "entities": [{ "id": "6f6532d5...", "name": "Pioneer Point Partners", "entity_type": "Organization" }]
}
```

--------------------------------

### Configure Cala MCP Server

Source: https://docs.cala.ai/integrations/mcp

JSON configuration templates for integrating the Cala MCP server into different AI agent environments. Requires a valid API key from the Cala console to authenticate requests.

```json
{
    "mcpServers": {
        "Cala": {
            "url": "https://api.cala.ai/mcp/",
            "headers": {
                "X-API-KEY": "YOUR_CALA_API_KEY"
            }
        }
    }
}
```

```json
{
    "mcpServers": {
        "Cala": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://api.cala.ai/mcp/",
                "--header",
                "X-API-KEY: YOUR_CALA_API_KEY"
            ]
        }
    }
}
```

```json
{
    "servers": {
        "Cala": {
            "type": "http",
            "url": "https://api.cala.ai/mcp/",
            "headers": {
                "X-API-KEY": "YOUR_CALA_API_KEY"
            }
        }
    }
}
```

--------------------------------

### Cala API Tool Selection - Knowledge Query

Source: https://docs.cala.ai/index

This entry describes the 'knowledge_query' tool for obtaining typed answers and querying in a structured interface using the Cala API. The associated endpoint is '/v1/knowledge/query'.

```markdown
| I want to...                                               |
| :--------------------------------------------------------- | 
| Obtained typed answers and Query in a Structured Interface |
| Use                | `knowledge_query` |
| Endpoint                   | `/v1/knowledge/query`      |
```

--------------------------------

### Cala API Tool Selection - Knowledge Search

Source: https://docs.cala.ai/index

This entry outlines the 'knowledge_search' tool available in the Cala API. It is used for asking free-text questions and requires the '/v1/knowledge/search' endpoint.

```markdown
| I want to...                                               |
| :--------------------------------------------------------- | 
| Ask a free-text question with sources                      |
| Use                | `knowledge_search` |
| Endpoint                   | `/v1/knowledge/search`     |
```

--------------------------------

### Structured Knowledge Query

Source: https://docs.cala.ai/api-reference/query

Search verified knowledge using structured dot-notation query syntax for filtering entities by attributes. The input field is named 'input'. This is useful for filtering entities by attributes like location, funding, industry, and year.

```json
{
  "input": "startups.location=Spain.funding＞10M.funding＜=50M"
}
```

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

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

--------------------------------

### POST /v1/knowledge/search

Source: https://docs.cala.ai/api-reference/search

Search verified knowledge using natural language questions. This endpoint is best for open-ended queries where you need explanations, context, and sources.

```APIDOC
## POST /v1/knowledge/search

### Description
Search verified knowledge using natural language questions. Best for open-ended queries where you need explanations, context, and sources — not just entity lists.

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

Use this when: You need a researched, sourced answer to a question. Prefer `knowledge_query` for structured filtering, or `entity_search` if you just need to find an entity by name.

### Method
POST

### Endpoint
https://api.cala.ai/v1/knowledge/search

### Parameters
#### Request Body
- **input** (string) - Required - The natural language question to search for.

### Request Example
```json
{
  "input": "What are the biggest AI startups in Europe by funding?"
}
```

### Response
#### Success Response (200)
- **content** (string) - A succinct answer to the user's input in Markdown format.
- **explainability** (array) - A list of reasoning steps to get to that answer.
- **context** (array) - A list of facts that support the answer.
- **entities** (array) - Entities identified in the answer.

#### Response Example
```json
{
  "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"
      ]
    }
  ]
}
```

#### Error Response (422)
- **detail** (array) - Details about the validation error.

#### Error Response (429)
- **error** (string) - Indicates the type of error, e.g., "rate_limit_exceeded".
- **message** (string) - A message explaining the error, e.g., "Rate limit per minute exceeded. Too many requests."
```