API Documentation
← All tools
GET
/api/v1/companiesSearch
companiesAvailable on FreeNo success wrapper
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.
When to use it
- Search companies by name or keyword
- Filter companies by sector, country, or business model
- Find companies with contact or leadership data available
Getting started
Base URL
https://app.caelrith.com/api/v1/toolsAuthentication
Include your API key in the x-api-key header.
Rate limit
Every call counts against your workspace’s daily quota for company-profiles. 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 |
|---|---|---|---|
| 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"
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