Returns a paginated list of company profiles with metadata including total item count, callable with free-text search and structured filters. Use it to find companies by name, domain, sector, location, or profile completeness. Invalid query parameters return HTTP 400.
Rate limit: company-profiles · Free plan: 10/day
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| page | number | No | Min 1; default 1 (min 1; default 1) Range: 1 to ∞ |
| limit | number | No | Range 1-200; default 20 (range 1-200; default 20) Range: 1 to 200 |
| search | string | No | Free-text query matched against company content; when supplied, results can be ranked by relevance. |
| query | string | No | maximum length 2000 |
| domain | string | No | Company website domain, e.g. example.com. |
| status | string | No | Company status value to filter by. |
| sector | string | No | Industry sector label. |
| subsector | string | No | More specific industry label within a sector. |
| business_model | string | No | Business model label to filter by. |
| country | string | No | Country name or code to filter by. |
| city | string | No | City name to filter by. |
| source_org_country | string | No | Country of the source organization associated with the company. |
| tech | string | No | Technology label to filter by. |
| founded_year_min | integer | No | Earliest founding year to include. |
| founded_year_max | integer | No | Latest founding year to include. |
| enrichment_version | integer | No | Only return companies at this enrichment version. |
| has_email | boolean | No | When true, only companies with an email address. |
| has_phone | boolean | No | When true, only companies with a phone number. |
| has_linkedin | boolean | No | When true, only companies with a LinkedIn profile. |
| has_leadership | boolean | No | When true, only companies with leadership information. |
| has_products | boolean | No | When true, only companies with product information. |
| has_embedding | boolean | No | When true, only companies that have an embedding. |
| sort | string | No | Field to order results by; relevance applies only when a search term is given, otherwise it falls back to last_updated. (default relevance) Allowed values: relevance, last_updated, processed_at, company_name, country, founded_year |
| order | string | No | Sort direction, ascending or descending. (default desc) Allowed values: asc, desc |
| include_embedding | boolean | No | When true, include the company embedding in each result. |
Example request
curl -H "x-api-key: YOUR_API_KEY" \ "https://app.caelrith.com/api/v1/companies"
Returns the profile for a single company identified by its domain, including its linked organizations. Call it when you already know a company's domain and need its details. Returns 404 if no company matches the domain, and 400 if the domain is malformed.
Rate limit: company-profiles · Free plan: 10/day
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| include_embedding | boolean | No | Set to false to omit the company's embedding from the response. |
| domain(path) | string | Yes | Company web domain, e.g. example.com. |
Example request
curl -H "x-api-key: YOUR_API_KEY" \
"https://app.caelrith.com/api/v1/companies/{domain}"Returns companies similar to the given company, ranked by cosine similarity, along with the source company and metadata about the result set. Use it to find comparable or related companies from a known domain. Fails with 404 if the company does not exist or has no similarity data available yet, 400 for invalid query parameters, and 503 if similarity search is temporarily unavailable.
Rate limit: company-similar · Free plan: 10/day
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | number | No | Maximum number of similar companies to return. (range 1-50; default 10) Range: 1 to 50 |
| min_similarity | number | No | Minimum cosine similarity a company must reach to be included. (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 each result's similarity vector in the response. |
| domain(path) | string | Yes | Company domain used to identify the source company. |
Example request
curl -H "x-api-key: YOUR_API_KEY" \
"https://app.caelrith.com/api/v1/companies/{domain}/similar"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.
Rate limit: company-similar · Free plan: 10/day
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"