REST API

Search for companies with a single HTTP request. Base URL: https://trycanonical.ai

Authentication

All API requests require an API key passed in the x-api-key header. Create keys from your Settings.

curl https://trycanonical.ai/api/v1/search?q=fintech \
  -H "x-api-key: sk_your_key"

Keys start with sk_. Keep them secret — they grant full API access to your account.

Search Companies

GET POST /api/v1/search

Query Parameters

Parameter	Type	Default	Description
q	string	required	Natural language search query
top_k	integer	20	Number of results (1–100)
verified	boolean	false	LLM verification for higher accuracy (uses 2 credits)

Example Request

curl "https://trycanonical.ai/api/v1/search?q=AI+healthcare+startups&top_k=5" \
  -H "x-api-key: sk_your_key"

Response

{
  "results": [
    {
      "id": 12345,
      "name": "Acme Health AI",
      "website": "https://acmehealthai.com",
      "logo_url": "https://logo.clearbit.com/acmehealthai.com",
      "domain": "acmehealthai.com",
      "description": "AI-powered diagnostic platform...",
      "verdict": null,
      "verdict_reason": null
    }
  ],
  "count": 5,
  "query": "AI healthcare startups",
  "credits_used": 1,
  "credits_remaining": 999
}

Response Fields

Field	Type	Description
results	Company[]	Array of matching companies
results[].id	integer	Unique company ID
results[].name	string	Company name
results[].website	string	Company website URL
results[].logo_url	string \| null	Logo image URL
results[].domain	string	Primary domain
results[].description	string	Company description
results[].verdict	string \| null	Relevance verdict (only when verified=true): "Relevant", "Partial", or "Irrelevant"
results[].verdict_reason	string \| null	Explanation of the verdict (only when verified=true)
count	integer	Number of results returned
query	string	Echo of the original query
credits_used	integer	Credits consumed (1 normal, 2 verified)
credits_remaining	integer \| null	Remaining credits for your account

Verified Search

Set verified=true to enable LLM-powered verification. Each result is classified as Relevant, Partial, or Irrelevant, and irrelevant results are removed from the response.

Batch Mode (default)

Returns all results after verification completes. Best for scripts and background jobs.

curl "https://trycanonical.ai/api/v1/search?q=fintech&verified=true" \
  -H "x-api-key: sk_your_key"

Streaming Mode (SSE)

Add Accept: text/event-stream to stream results as they are verified. Best for real-time UIs.

curl -N "https://trycanonical.ai/api/v1/search?q=fintech&verified=true" \
  -H "x-api-key: sk_your_key" \
  -H "Accept: text/event-stream"

SSE Event Types

Event	Description
preview	Initial unverified results for immediate display
preview_remove	Company IDs to remove from preview (found irrelevant)
progress	Verification progress update (phase, verified count, total)
batch	Batch of verified results
partial_batch	Partially verified results (when verification times out)
done	Stream complete — contains final count and credits
error	Error occurred during search
heartbeat	Keep-alive signal (every ~15 seconds)

Rate Limits

Limits are enforced per account. Every response includes rate limit headers.

Plan	Daily Limit	Per Minute
Guest	200	10
Free	1,000	20
Starter	5,000	30
Pro	50,000	100
Enterprise	Unlimited	500

Rate Limit Headers

Header	Description
X-RateLimit-Limit	Your daily request limit
X-RateLimit-Remaining	Requests remaining today
X-RateLimit-Reset	Unix timestamp when the limit resets

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with a detail field.

Status	Meaning	Body
401	Missing or invalid API key	{"detail": "API key required. Include x-api-key header."}
429	Rate limit exceeded	{"error": "Rate limit exceeded"}
500	Internal server error	{"detail": "Internal server error"}

Credits

Each search consumes 1 credit. Verified searches consume 2 credits. Credits used and remaining are included in every response.