Similar Search

companiesAvailable on FreeNo success wrapper

Returns companies ranked by similarity to a free-text query, with metadata on the query, number returned, and how many candidates were skipped. Call it to find companies matching a description or concept rather than an exact name. Fails with 400 for invalid parameters and 503 when the similarity service is unavailable.

When to use it

Find companies similar to a free-text description
Discover companies by concept within a sector or country
Surface near-duplicate or related companies for a query

Getting started

Base URL

https://app.caelrith.com/api/v1/tools

Authentication

Include your API key in the x-api-key header.

Rate limit

Every call counts against your workspace’s daily quota for company-similar. Exceeding it returns HTTP 429.

Plans and daily limits

Plan	Available	Calls / day
free	yes	10
pro	yes	200
custom (default)	yes	10,000

Plan defaults. A custom workspace may carry per-tenant overrides.

Parameters

Query parameters

Parameter	Type	Required	Description
limit	number	No	Maximum number of companies to return. (range 1-50; default 10) Range: 1 to 50
min_similarity	number	No	Similarity threshold; results below this score are excluded. (range -1-1) Range: -1 to 1
sector	string	No	Restrict results to companies in this sector.
country	string	No	Restrict results to companies in this country.
status	string	No	Restrict results to companies with this status.
include_embedding	boolean	No	When true, include the company's similarity representation in each result.
q	string	Yes	Free-text query describing the company or concept to match against.
page	number	No	Min 1; default 1 (min 1; default 1) Range: 1 to ∞
has_email	boolean	No	booleans arrive as strings - send 'true' or 'false'; value is parsed from the raw query string and coerced server-side

Example request

curl -H "x-api-key: YOUR_API_KEY" \
  "https://app.caelrith.com/api/v1/companies/similar?q=your_q"

Response envelope

This endpoint returns an implicit 2xx response - there is no success flag in the body.

{
  "data": { /* payload */ },
  "meta": { /* pagination, totals */ }
}

// No "success" flag on this endpoint - any 2xx JSON is a success.

Catalog version mcp-2026-10-28 · generated from the live MCP catalog