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: YOUR_API_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)
intent	string	inferred	Optional ranking profile applied after relevance filtering. Pass it when your client (e.g. an agent reading the user's goal from chat or memory) already knows the right slug; omit it to let the server infer intent from the query text. Allowed slugs: sales_prospecting, sales_timing, sales_expansion, competitive_tracking, emerging_competitor_scan, talent_source, recruiter_employer_vet, jobseeker_stability, jobseeker_growth.

Intent slugs

Each slug controls how the verified result set is reordered. The ranker uses precomputed signals (hiring direction, momentum, retention, talent magnetism, brand reach) so picking an intent doesn't run a second search — it just changes the sort.

Slug	When to pick it	What the ranker optimizes for
sales_prospecting	Top-of-funnel outbound list with no specific buying-window constraint. Generic ICP fit.	Companies actively growing, hiring, with brand reach.
sales_timing	"Who is buying now?" — near-term buying window.	Recent hiring acceleration paired with healthy growth.
sales_expansion	Existing customers ripe for upsell, cross-sell, or deepening.	Stable, steadily-growing companies with strong retention.
competitive_tracking	Monitoring named competitors' direction and posture.	Hiring-direction shifts, momentum, brand reach, geo footprint.
emerging_competitor_scan	Discovering new entrants / rising challengers.	Fast-growing, aggressively hiring companies with rising visibility.
talent_source	Recruiter / hiring manager looking for companies to poach from.	Hiring in target function, alumni footprint, team pedigree, retention.
recruiter_employer_vet	Evaluating whether to send a candidate to a particular company.	Employer retention, stability, talent demand, brand reach.
jobseeker_stability	Job seeker prioritizing job security ("is this company safe?").	Low churn, positive net flow, retention, moderate momentum.
jobseeker_growth	Job seeker prioritizing career upside ("where can my career accelerate?").	High momentum, growth-function hiring, talent magnetism, hiring velocity.

Example Request

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

# Intent-ranked (sales prospecting):
curl "https://trycanonical.ai/api/v1/search?q=AI+healthcare+startups&top_k=20&intent=sales_prospecting" \
  -H "x-api-key: YOUR_API_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...",
      "headquarters": "San Francisco, CA",
      "employee_count": 150,
      "dimensions": {
        "industry": ["Healthcare", "Artificial Intelligence"],
        "technology": ["Machine Learning", "NLP"]
      }
    }
  ],
  "count": 5,
  "query": "AI healthcare startups",
  "credits_used": 5,
  "credits_remaining": 995
}

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[].headquarters	string \| null	Company headquarters location
results[].employee_count	integer \| null	Number of employees
results[].dimensions	object \| null	Classification tags (industry, technology, etc.)
count	integer	Number of results returned
query	string	Echo of the original query
credits_used	integer	Credits consumed (1 credit per result row)
credits_remaining	integer \| null	Remaining credits for your account

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 result row consumes 1 credit. A search returning 20 results uses 20 credits. Credits used and remaining are included in every response.