> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cala.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search 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 with IDs you can pass to retrieve_entity.


Examples:

`{"name": "OpenAI"}`

`{"name": "Elon Musk", "entity_types": ["Person"]}`

`{"name": "Berlin", "entity_types": ["GPE", "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` for attribute-based filtering instead.



## OpenAPI

````yaml https://api.cala.ai/openapi.json get /v1/entities
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/entities:
    get:
      tags:
        - API v1
        - Entities
      summary: Search Entities
      description: >-
        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 with IDs you can pass to
        retrieve_entity.



        Examples:


        `{"name": "OpenAI"}`


        `{"name": "Elon Musk", "entity_types": ["Person"]}`


        `{"name": "Berlin", "entity_types": ["GPE", "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` for attribute-based filtering
        instead.
      operationId: entity_search
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            description: Entity name to search for
            title: Name
          description: Entity name to search for
          example: <entity-name>
        - name: entity_types
          in: query
          required: false
          schema:
            type: array
            items:
              enum:
                - Entity
                - Animal
                - Award
                - Organization
                - Company
                - EducationalInstitution
                - Person
                - Event
                - GPE
                - Country
                - CountryRegion
                - Industry
                - FinancialMetric
                - Group
                - CorporateEvent
                - PrivateCompanyFundingRound
                - Facility
                - Location
                - Organism
                - Plant
                - Product
                - Sanction
                - WorkOfArt
                - Law
                - Language
                - Exchange
                - Future
                - Commodity
                - PositioningMetric
                - MacroIndicatorPublication
                - MacroIndicator
              type: string
            description: Filter by entity types
            default: []
            title: Entity Types
          description: Filter by entity types
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: Maximum number of results
            default: 20
            title: Limit
          description: Maximum number of results
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySearchResponse'
        '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 exceeded. Too many requests.
      security:
        - APIKeyHeader: []
components:
  schemas:
    EntitySearchResponse:
      properties:
        entities:
          items:
            $ref: '#/components/schemas/Entity'
          type: array
          title: Entities
          description: >-
            List of entities matching the search query, ordered by relevance
            (most relevant first).
      type: object
      required:
        - entities
      title: EntitySearchResponse
      description: Response containing a list of entities matching the search query.
      example:
        entities:
          - description: An American multinational technology company.
            entity_type: Company
            id: e5bb591a-d308-4aa5-9672-96046d366cde
            name: OpenAI
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Entity:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: The ID of the entity
          examples:
            - e5bb591a-d308-4aa5-9672-96046d366cde
        name:
          type: string
          title: Name
          description: The name of the entity
          examples:
            - OpenAI
        entity_type:
          type: string
          enum:
            - Entity
            - Animal
            - Award
            - Organization
            - Company
            - EducationalInstitution
            - Person
            - Event
            - GPE
            - Country
            - CountryRegion
            - Industry
            - FinancialMetric
            - Group
            - CorporateEvent
            - PrivateCompanyFundingRound
            - Facility
            - Location
            - Organism
            - Plant
            - Product
            - Sanction
            - WorkOfArt
            - Law
            - Language
            - Exchange
            - Future
            - Commodity
            - PositioningMetric
            - MacroIndicatorPublication
            - MacroIndicator
          title: Entity Type
          description: The type of the entity
          examples:
            - Company
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: A short description of the entity
          examples:
            - An American multinational technology company.
      type: object
      required:
        - id
        - name
        - entity_type
      title: Entity
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY

````