API and MCP

1. Create a free account.
2. Your key is shown once, at sign-up. If you did not copy it, create a new one on Keys and MCP in the customer app.
3. Paste the setup line for your assistant. The reference below has the line for each one.

Create a free account Plans and limits

A free key is 60 requests a minute, with a burst of 20 requests in 5 seconds, and 1,000 a day. Downloads of open files do not use that allowance.

Version 1.1 on Zenodo, Kaggle and Hugging Face, 15 gates. A gate is a fixed polygon on a passage.

Extras, with a free key: GET /v1/arctic/gates/{gate}/imagery and GET /v1/datasets/arctic-open-water-window/extras. MCP tool: get_arctic_imagery. The download holds the tables.

Example questions

• When did the Bering Strait gate open last season?
• List the full-size file for gate bering-strait in week 29 of 2024.
• How many open-water days did the Vilkitsky Strait gate have in 2023?

Not for navigation. Use at your own risk. Provided as is, without warranty of any kind. Data disclaimers.

Version 1.1 on Zenodo, Kaggle and Hugging Face, 19 series on 18 lakes, monthly. Weekly lake areas are planned.

Extras, with a free key: GET /v1/lakes/{lake}/imagery and GET /v1/datasets/western-terminal-lakes/extras. MCP tool: get_lake_imagery. The download holds the monthly tables.

Example questions

• What was Walker Lake's open-water area in August 2024?
• Give me the full Sentinel-2 composite for Great Salt Lake south in summer 2024.
• Which summer preview images are in the Western Terminal Lakes download?

Not for water-rights, legal or engineering decisions. Data disclaimers.

Version 1.2 on Zenodo, Kaggle and Hugging Face, 672 storms.

Extras, with a free key: GET /v1/storms/{event_id}/track, /forecasts, /media, GET /v1/tracks (track search), and GET /v1/datasets/storm-blackout/extras. MCP tools: get_storm_track, get_storm_forecasts, get_storm_media, find_storm_track, find_storms_near, get_power_outage. The download holds the tables.

Example questions

• Show me Hurricane Milton's track.
• Show the forecast lines for Hurricane Irma.
• How many customers lost power in Lee County, Florida during Milton?

Estimates from public records and satellite night light. Not for real-time emergency response or for any decision about one address or property. Data disclaimers.

Every method serves the same data. Downloads need no account; the API and MCP server use your API key, with access and quotas set by your plan.

How to connect each assistant

HEIMDALL_API_KEY="${HEIMDALL_API_KEY:-}"
if [ -z "$HEIMDALL_API_KEY" ]; then echo "HEIMDALL_API_KEY is empty. Create a key on the Keys and MCP page, then run: export HEIMDALL_API_KEY='paste the key'"; exit 1; fi
claude mcp add --transport http heimdall https://api.heimdallresearch.com/mcp/ --header "Authorization: Bearer $HEIMDALL_API_KEY"

HEIMDALL_API_KEY="${HEIMDALL_API_KEY:-}"
if [ -z "$HEIMDALL_API_KEY" ]; then echo "HEIMDALL_API_KEY is empty. Create a key on the Keys and MCP page, then run: export HEIMDALL_API_KEY='paste the key'"; exit 1; fi
codex mcp add heimdall --url https://api.heimdallresearch.com/mcp/ --bearer-token-env-var HEIMDALL_API_KEY

HEIMDALL_API_KEY="${HEIMDALL_API_KEY:-}"
if [ -z "$HEIMDALL_API_KEY" ]; then echo "HEIMDALL_API_KEY is empty. Create a key on the Keys and MCP page, then run: export HEIMDALL_API_KEY='paste the key'"; exit 1; fi
cat <<EOF
{
  "mcpServers": {
    "heimdall": {
      "url": "https://api.heimdallresearch.com/mcp/",
      "headers": {
        "Authorization": "Bearer $HEIMDALL_API_KEY"
      }
    }
  }
}
EOF

HEIMDALL_API_KEY="${HEIMDALL_API_KEY:-}"
if [ -z "$HEIMDALL_API_KEY" ]; then echo "HEIMDALL_API_KEY is empty. Create a key on the Keys and MCP page, then run: export HEIMDALL_API_KEY='paste the key'"; exit 1; fi
cat <<EOF
{
  "servers": {
    "heimdall": {
      "type": "http",
      "url": "https://api.heimdallresearch.com/mcp/",
      "headers": {
        "Authorization": "Bearer $HEIMDALL_API_KEY"
      }
    }
  }
}
EOF

HEIMDALL_API_KEY="${HEIMDALL_API_KEY:-}"
if [ -z "$HEIMDALL_API_KEY" ]; then echo "HEIMDALL_API_KEY is empty. Create a key on the Keys and MCP page, then run: export HEIMDALL_API_KEY='paste the key'"; exit 1; fi
cat <<EOF
{
  "mcpServers": {
    "heimdall": {
      "serverUrl": "https://api.heimdallresearch.com/mcp/",
      "headers": {
        "Authorization": "Bearer $HEIMDALL_API_KEY"
      }
    }
  }
}
EOF

Assistants connect with an API key today. Connecting Claude or ChatGPT by signing in is not available yet.

Your key works in any tool that lets you set a request header.

Assistant setup follows each product's documentation: Claude Code, Codex, Cursor, VS Code, Windsurf, Claude custom connectors, ChatGPT connector authentication.

1. curl

   curl https://api.heimdallresearch.com/v1/arctic/gates/bering-strait/seasons \
     -H "Authorization: Bearer $HEIMDALL_API_KEY"

2. Python

   import os
   import requests
   
   r = requests.get(
       "https://api.heimdallresearch.com/v1/arctic/gates/bering-strait/seasons",
       headers={"Authorization": f"Bearer {os.environ['HEIMDALL_API_KEY']}"},
       timeout=30,
   )
   r.raise_for_status()
   seasons = r.json()

3. JavaScript (Node.js 18 or later)

   const r = await fetch(
     "https://api.heimdallresearch.com/v1/arctic/gates/bering-strait/seasons",
     { headers: { Authorization: `Bearer ${process.env.HEIMDALL_API_KEY}` } },
   );
   if (!r.ok) throw new Error(`HTTP ${r.status}`);
   const seasons = await r.json();

4. R (httr2 package)

   library(httr2)
   
   seasons <- request("https://api.heimdallresearch.com/v1/arctic/gates/bering-strait/seasons") |>
     req_auth_bearer_token(Sys.getenv("HEIMDALL_API_KEY")) |>
     req_perform() |>
     resp_body_json()

Extras routes and MCP tools

Example prompts

Example prompts

Not in this download, free through the API: full-size radar images of the 15 gates, 2015 to 2026, for the weeks that have a usable one. Get a free key.

Not in this download, free through the API: full-size summer satellite images of all 18 lakes and reservoirs, 2019 to 2026. Get a free key.

Not in this download, free through the API: lights-out videos for most storms, storm-path videos for hurricanes and tropical storms, forecast maps and satellite loops. Get a free key.

Free key

60 requests a minute, with a burst of 20 requests in 5 seconds, and 1,000 a day, for every free dataset.

Early access

Paid products are free to every account through December 31, 2026 (midnight US Eastern). From January 1, 2027, paid plans apply only to accounts that choose one, and the free API key and free tier continue. Storm reports for storms already in the published tables, and the extras listed for those tables, are free with a free account. Licensed products are by quote. Open dataset downloads stay free forever.

Paid plans

Free: 60 requests a minute, with a burst of 20 requests in 5 seconds, and 1,000 a day. Pro: 10,000 requests a day. Team: 100,000 requests a day. See plans and prices.

Licensed data

The same API and MCP server deliver licensed products, with a key scoped to your organization and product. Limits are set in your license.

When you hit a limit

The API answers 429 with a Retry-After header. Every response reports your remaining calls.

Keys

Shown once, stored only as a hash, limited to the datasets you choose, and revocable at any time.

Rules of use

What you may and may not do with the data, in plain words: the Data Use Policy. The Terms apply if the two differ.

{
  "error": {
    "code": "unauthorized",
    "message": "No API key was sent with this request. Get a free key at https://app.heimdallresearch.com/sign-up",
    "docs_url": "https://heimdallresearch.com/developers/#errors"
  }
}

Error codes returned by the API and MCP server

Status

Open. Free keys, the REST API and the MCP server are live.

Datasets

Arctic Open-Water Window 1.1, Western Terminal Lakes 1.1 and Storm Blackout and Restoration 1.2, each on Zenodo, Kaggle and Hugging Face. Weekly lakes are planned.

API reference

Endpoints, parameters and response fields