API Reference

The Circumpolar.ai API lets you ask plain-language questions about any Arctic location and get data-backed answers. One endpoint, one key, works from any language.

Base URL: https://circumpolar.ai/api/v1

Authentication

All requests must include your API key as a Bearer token in the Authorization header. Get your key from the dashboard.

shell

Authorization: Bearer cpol_YOUR_KEY

Keep your key secret. If exposed, revoke it from the dashboard and generate a new one.

POST /v1/insights

Ask a question about an Arctic location. The response includes a direct, data-backed answer from Circe, optional location echo, and your current usage.

Request body

questionrequired

string

Plain-language question about the location.

lat

number

Latitude of the location (decimal degrees, positive = North).

lon

number

Longitude of the location (decimal degrees, negative = West).

location_name

string

Human-readable place name. Used in the answer if provided.

Response

json

{
  "answer": "At 64.84°N, 147.72°W (Fairbanks, Alaska), permafrost is discontinuous and degrading rapidly. Active layer depth ranges from 0.5–1.5m depending on vegetation and drainage. Ground ice content is high in silty soils, putting infrastructure at significant thaw settlement risk. Mean annual ground temperature at 1m depth is approximately -0.5°C to -2°C, close to the thaw threshold. Risk rating: HIGH for any uninsulated foundation or buried utility line. Recommended: thermosyphon pilings or elevated structures with ventilated crawl space. Data: USGS Alaska permafrost layers, GTN-P borehole network.",
  "location": {
    "lat": 64.8378,
    "lon": -147.7164,
    "name": null
  },
  "usage": {
    "used": 3,
    "limit": 1000,
    "plan": "pro"
  }
}

Fields

answer

string

Circe's answer: direct, specific, under 300 words unless the question warrants more.

location

object | null

Echo of the location you sent, or null if no coordinates were provided.

usage.used

number

Number of queries used this month (updated after this request).

usage.limit

number

Your monthly query limit for this plan.

usage.plan

string

Your current plan: free or pro.

Error codes

401

Unauthorized

Missing or invalid API key.

400

Bad Request

Missing required question field.

429

Too Many Requests

Monthly query limit reached. Upgrade at circumpolar.ai/dashboard.

GET /v1/permafrost

Returns permafrost zone, thaw risk, mean annual ground temperature (MAGT), and active layer thickness (ALT) for any coordinate in Alaska and Canada. Unlike the /v1/insights endpoint, this is a deterministic lookup — same coordinates and date always return the same structured values with confidence intervals. Pass an optional date to monitor a location at a past or future point in time; MAGT and ALT are shifted by a published Arctic warming trend (~0.65°C/decade, Rantanen 2022 / NOAA Alaska) anchored to the 2010 calibration baseline. Confidence widens for dates far from baseline.

Request

latrequired

float

Latitude in decimal degrees (−90 to 90).

lngrequired

float

Longitude in decimal degrees (−180 to 180).

date

ISO 8601 date

Optional. YYYY-MM-DD between 1950-01-01 and 2100-12-31. Defaults to today. Projects MAGT/ALT via Arctic warming trend; zone classification is static (IPA 1997–2002).

Zone values

continuous90–100% of area coveredrisk 0.90

discontinuous50–90% of area coveredrisk 0.65

sporadic10–50% of area coveredrisk 0.35

isolated0–10% of area coveredrisk 0.10

noneNo permafrostrisk 0.00

Example response

json

{
  "lat": 64.84,
  "lng": -147.72,
  "date": "2026-05-15",
  "zone": "discontinuous",
  "risk": {
    "score": 0.65,
    "label": "High",
    "confidence": 0.80
  },
  "mean_annual_ground_temperature_c": {
    "estimate": 0.6,
    "low": -2.4,
    "high": 3.6,
    "confidence": 0.64,
    "unit": "celsius"
  },
  "active_layer_thickness_m": {
    "estimate": 1.6,
    "low": 1.1,
    "high": 2.2,
    "confidence": 0.64,
    "unit": "meters"
  },
  "metadata": {
    "data_source": "IPA zones (Brown et al. 1997); MAAT from ASTER DEM elevation + Alaska latitude model; ALT from Stefan equation (CALM calibration); Arctic warming trend per Rantanen et al. 2022 / NOAA Alaska",
    "resolution_deg": 0.25,
    "climate_baseline_year": 2010,
    "warming_rate_c_per_decade": 0.65,
    "disclaimer": "Statistical estimates. Past/future projections apply a linear Arctic warming trend; accuracy degrades for dates far from 2010. Field investigation required before any engineering decision."
  },
  "usage": { "used": 1, "limit": 500, "plan": "free" }
}

shell

# Current conditions
curl "https://circumpolar.ai/api/v1/permafrost?lat=64.84&lng=-147.72" \
  -H "Authorization: Bearer cpol_YOUR_KEY"

# Project to a future date (or query a past date)
curl "https://circumpolar.ai/api/v1/permafrost?lat=64.84&lng=-147.72&date=2050-06-01" \
  -H "Authorization: Bearer cpol_YOUR_KEY"

Kotzebue example

The siting map at circumpolar.ai/kotzebue is rendered directly from this endpoint. At server-render time the page samples a 0.05° grid over the Kotzebue area (lat 65.5° to 68°, lon -164.5° to -160.5°), calls the same lookupPermafrost function that backs this API, filters cells where zone === "none" (ocean), and paints the surviving land cells onto a MapLibre overlay. Around Kotzebue the API returns continuous and discontinuous zones, with MAGT estimates blended from both source layers.

Source data: Pastick et al. 2015 (Alaska, 0.05° native) fused with Obu et al. 2019 (circumpolar, 0.1° native), bilinearly interpolated at the query point and warming-trend-adjusted from a 2010 climate baseline. Confidence reflects source agreement plus date-distance from baseline. Field investigation required before any engineering or construction decision.

Rate limits

PlanQueries / monthPrice

Free10$0

Pro1,000$10/mo

Limits reset on the 1st of each month UTC. Need more? Email support@beaded.cloud.

MCP server (AI terminals)

Add Circumpolar.ai as an MCP server and your AI assistant (Claude Code, Cursor, Windsurf) can call it natively. No copy-paste required. Ask your AI about permafrost risk at any location and it will fetch the answer automatically.

json

// ~/.claude/settings.json
{
  "mcpServers": {
    "circumpolar": {
      "command": "npx",
      "args": ["circumpolar-mcp"],
      "env": {
        "CIRCUMPOLAR_API_KEY": "cpol_YOUR_KEY"
      }
    }
  }
}

Then restart your terminal. Your AI will have a circumpolar_insights tool available automatically.

Examples

curl

shell

curl https://circumpolar.ai/api/v1/insights \
  -H "Authorization: Bearer cpol_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the permafrost risk at this location?",
    "lat": 64.8378,
    "lon": -147.7164
  }'

Python

python

import requests

res = requests.post(
    "https://circumpolar.ai/api/v1/insights",
    headers={"Authorization": "Bearer cpol_YOUR_KEY"},
    json={
        "question": "What is the permafrost risk at this location?",
        "lat": 64.8378,
        "lon": -147.7164,
    },
)
data = res.json()
print(data["answer"])

JavaScript / TypeScript

typescript

const res = await fetch("https://circumpolar.ai/api/v1/insights", {
  method: "POST",
  headers: {
    Authorization: "Bearer cpol_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    question: "What is the permafrost risk at this location?",
    lat: 64.8378,
    lon: -147.7164,
  }),
});

const { answer, usage } = await res.json();
console.log(answer);

Questions? support@beaded.cloud · Get your API key