Authentication

Authentication

All Canopi API endpoints (except /v1/health) require authentication via an API key.

Using your key

Include your API key in the X-API-Key header with every request:

curl -H "X-API-Key: cnpi_live_your_api_key_here" \
  https://api.canopitech.ai/v1/species

headers = {"X-API-Key": "cnpi_live_your_api_key_here"}
response = httpx.get("https://api.canopitech.ai/v1/species", headers=headers)

Key format

Canopi API keys follow this format:

cnpi_live_[32 hexadecimal characters]

The cnpi_live_ prefix identifies it as a Canopi production key. Keep your key secure — treat it like a password. Don’t commit it to version control or expose it in client-side code.

Access tiers

Canopi API access is organized into three tiers, named for the stages of fungal growth:

Spore

The beginning. Free access for exploration, evaluation, and small-scale experimentation.

Requests per day	100
Batch size	Up to 10 sites per call
Best for	Evaluation, prototyping, hackathons

Mycel

The network forming. For partners integrating Canopi into their platform or workflow.

Requests per day	10,000
Batch size	Up to 100 sites per call
Best for	Platform integrations, operational tools

Hypha

Full reach. For organizations building reforestation intelligence into their core operations.

Requests per day	Unlimited
Batch size	Up to 500 sites per call
Best for	Enterprise integrations, portfolio-scale analysis

Rate limiting

When you exceed your daily request limit, the API returns HTTP 429 with a Retry-After header indicating seconds until midnight UTC, when the counter resets.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You've reached your daily request limit for the spore tier. Resets at midnight UTC."
  }
}

Each individual request to any endpoint counts as one request. A batch call with 10 sites counts as one request, not ten.

Getting a key

Request access at canopitech.ai. Spore-tier keys are available immediately. Mycel and Hypha tiers are provisioned through direct partnership.