---
title: "Search Entities"
method: POST
path: "/entities/search"
tags: ["entities"]
---

# Search Entities

`POST /entities/search`

Semantic search over entities by cosine similarity to the query embedding.

POST (not GET) because vectors don't fit nicely in querystrings — and we
may want to extend the request body with filters later.

## Request body

- EntitySearchRequest
  - `query` string, required
  - `type` string, nullable
  - `limit` integer

## Response `200`

Successful Response

- EntitySearchResponse
  - `items` EntityWithScoreResponse[], required
    - `id` string, uuid, required
    - `type` string, required
    - `name` string, required
    - `description` string, nullable
    - `attributes` object
    - `mention_count` integer, required
    - `first_seen_resource_id` string, nullable
    - `last_seen_resource_id` string, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `similarity` number, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/hyperspell/apis/hyperspell-api.md) · [All operations](https://skmtc.net/hyperspell/apis/hyperspell-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hyperspell/hyperspell-api/revisions/5721acd588e6/schema)