Python SDK

pip install canonical-search

from canonical_search import CanonicalClient

client = CanonicalClient(api_key="sk_your_key")
results = client.search("AI healthcare startups")

for company in results.results:
    print(f"{company.name} — {company.domain}")
    print(f"  {company.description[:100]}")

client = CanonicalClient(
    api_key="sk_your_key",
    base_url="https://trycanonical.ai",  # default
    timeout=30.0,                          # default
)

export CANONICAL_API_KEY=sk_your_key
export CANONICAL_API_BASE_URL=https://trycanonical.ai  # optional
export CANONICAL_TIMEOUT=30.0                          # optional

results = client.search(
    query="B2B SaaS companies",
    top_k=50,          # 1-100, default 20
    verified=True,     # LLM verification, default False
)

results = await client.asearch(
    query="B2B SaaS companies",
    top_k=50,
    verified=True,
)

class SearchResponse:
    results: list[Company]    # Matching companies
    count: int                # Number of results
    query: str                # Original query
    credits_used: int         # Credits consumed
    credits_remaining: int | None  # Remaining credits

class Company:
    id: int
    name: str
    website: str
    logo_url: str | None
    domain: str
    description: str
    verdict: str | None         # Only when verified=True
    verdict_reason: str | None  # Only when verified=True

from canonical_search import CanonicalClient
from canonical_search.exceptions import (
    AuthenticationError,
    RateLimitError,
    APIError,
)

client = CanonicalClient(api_key="sk_your_key")

try:
    results = client.search("fintech")
except AuthenticationError:
    print("Invalid or missing API key")
except RateLimitError:
    print("Rate limit exceeded — wait and retry")
except APIError as e:
    print(f"API error: {e}")