---
title: "Semantic Search"
method: POST
path: "/v2/semantic-search"
tags: ["Semantic Search"]
---

# Semantic Search

`POST /v2/semantic-search`

Perform an AI-powered semantic search. Use the `entityType` field in the request body to specify which entity type to search. Currently only supports companies.

The `prompt` field accepts natural language describing the companies to find. Supported query dimensions include:

- Industry or sector
  - Example: `climate tech companies in our pipeline`
- Descriptive technology or business concepts
  - Example: `biotech companies working on extracellular vesicles`
- Funding information: investment stage, funding date, amount raised, and year founded
  - Example: `Series A companies that raised more than $10M`
- Employee metrics: headcount, hiring rate, and departure rate
  - Example: `companies with more than 100 employees`
- Interaction history
  - Example: `companies our firm emailed recently`
- Relationship strength
  - Example: `companies where we have strong connections`
- Relative time references
  - Example: `AI companies founded in the past 3 years`
- Headquarters location: city, state, country, or region
  - Example: `fintech startups in San Francisco`
- Investor name
  - Example: `companies backed by Sequoia Capital`

These dimensions can be combined in a single prompt, for example `climate tech companies in San Francisco that raised a Series A in the past year`.

Results can be sorted by including the desired sort in the prompt itself, for example `Series B companies with the most funding`. Only one sortable attribute is supported per request.

Use the `listIds` field to scope results to companies on specific lists, and combine it with `prompt` to search semantically within those lists. Retrieve list IDs from `GET /v2/lists`.

The phrases `I`, `we`, and `our firm` always refer to firm-wide data: interaction history and relationship strength cannot be filtered to a specific team member. The phrases `in our pipeline` and `in our network` match companies your firm has interacted with or added to Affinity in general. They do not search for membership in a list literally named "Pipeline" or similar. To search a specific named list, use `listIds`.

The following are not supported:

- Third-party enrichment data such as Crunchbase, PitchBook, or Dealroom.
- Company valuation and revenue metrics.
- Lookup by similarity to a named company, for example `companies like OpenAI`.
- Notes, email body content, or file attachments.
- Custom fields.
- Computed or formula-based sorts, such as a ratio between two fields.

## Request body

- SemanticSearchCriteria — Semantic search criteria including search prompt and entity type
  - `prompt` string, required — The search prompt to apply.
  - `limit` integer — Number of items to include in the response.
  - `entityType` 'companies' — The type of entity to search for.
  - `listIds` integer[] — The IDs of the lists to filter results by.

## Response `201`

Created

- SemanticSearchResult — Includes the list of entities that matched the search prompt and the explanation for the search.
  - `data` CompaniesSemanticSearchCompany[], required — The list of entities that matched the search prompt
    - `id` integer, required — The company's unique identifier
    - `name` string, required — The company's name
    - `domain` string, hostname, nullable, required — The company's primary domain
    - `domains` string[], required — All of the company's domains
    - `isGlobal` boolean, required — Whether or not the company is tenant specific
    - `score` string, required — The calculated relevance score for the company against the search prompt.
  - `entityType` 'companies', required — The type of entity that was searched.
  - `explanation` string, required

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `default` — Errors

---

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