API Documentation

Get started in 5 minutes

curl -s "https://calchis.com/api/v1/events/live" \
  -H "Accept: application/json" | jq .

Code Examples

curl -s "https://calchis.com/api/v1/risk/score?lat=29.76&lng=-95.37&perils=hurricane" \
  -H "Authorization: Bearer YOUR_TOKEN" | jq .

curl -s "https://calchis.com/api/v1/risk/score?lat=29.76&lng=-95.37&perils=hurricane&format=oasis" \
  -H "Authorization: Bearer YOUR_TOKEN" -o hazard_score.json

curl -X POST "https://calchis.com/api/v1/triggers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gulf Hurricane CAT3+ Monitor",
    "peril": "hurricane",
    "lat": 29.76,
    "lng": -95.37,
    "radius_km": 200,
    "threshold_type": "wind_speed",
    "threshold_value": 96,
    "threshold_unit": "kt",
    "alert_at_pct": 80,
    "notes": "Alert when a storm reaches 80% of CAT3 threshold within 200km of Houston"
  }'

Base URL

Authentication

Rate Limits

All API routes use sliding-window rate limiting. Rate limit headers X-RateLimit-Remaining and X-RateLimit-Reset are included on every response. Exceeding the limit returns 429 with a Retry-After header.

Response Format

Event feeds return OGC-compliant GeoJSON FeatureCollections. Each feature includes a Point geometry (WGS84 coordinates as [lng, lat]) and a properties object with event metadata, severity, status, and source provenance.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-118.2437, 34.0522]
      },
      "properties": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "title": "M5.2 Earthquake — Los Angeles, CA",
        "event_type": "earthquake",
        "severity": 5.2,
        "severity_label": "M5.2 MODERATE",
        "status": "active",
        "started_at": "2026-03-20T14:23:00Z",
        "source": "usgs",
        "source_url": "https://earthquake.usgs.gov/earthquakes/eventpage/ci12345678",
        "confidence_score": 1.0,
        "slug": "m52-earthquake-los-angeles-ca-2026-03-20"
      }
    }
  ]
}

Events

Live US multi-peril disaster event feeds

Analysis

Deterministic event analysis, predictions, and timelines

Scenarios

What-if scenario planning for tabletop exercises and preparedness

Infrastructure

HIFLD critical infrastructure (hospitals, fire stations, schools, EMS)

Scoring

Multi-peril hazard scores with full methodology transparency

Portfolio

Portfolio management and exposure analysis

Triggers

ILS parametric trigger monitoring for cat bond positions

Locations

Saved locations with alerting and exposure checking

MCP server for agents

Calchis is also a Model Context Protocol tool server, so your own agent can call it: JSON-RPC 2.0 over the Streamable HTTP transport at POST /api/v1/mcp. Calchis calls no model — yours is the only one in the loop. Every message needs an API key; each tool call counts once against the same daily quota as the REST API, and a call refused for its arguments or its plan is not counted.

{
  "mcpServers": {
    "calchis": {
      "type": "http",
      "url": "https://calchis.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer cs_live_YOUR_KEY" }
    }
  }
}

Errors are JSON-RPC errors, never an HTTP 500: -32602 unknown tool or bad arguments, -32001 missing or invalid key (HTTP 401), -32002 daily quota spent (with reset_at), -32003 plan does not include the tool (with upgrade_to), -32004 not found. Scores are hazard scores, not risk scores; footprints are labeled observed or modeled on every feature. Full contract in docs/openapi.yaml under /mcp.

Output Formats

The record

What Calchis keeps rather than computes: every federal product as received, and the records derived from it with provenance on every row. These are the endpoints a data team integrates first; the integration quickstart walks the manifest, a day of the export, verifying a body against the archive and the public ledger, and citing a month of the revision record. All are public and read without a key, except the bulk export, which takes any account’s key and counts one call per page. Each record’s method is a document at /docs/<name>.md (listed below under the OpenAPI section); the datasets and their record= names are on /data.

Walk a day of the bulk export: request ?record=warning-exposures&day=2026-11-05, read rows until the response carries no X-Next-After header, and pass that header back as &after= until it does. Every row is the table’s own columns; nothing is renamed on the way out.

Data Standards