Quickstart - Mireye

This walkthrough makes three real API calls. No SDK, no install — just curl, jq, and a Mireye API token. We’ll ask about a Manhattan rooftop, fetch the same location’s flood-risk preset, and then wire up the hosted MCP server for Claude Code.

1. Pick a coordinate

Use any US lat/lng. We’ll use the corner of Beekman and Park Row in lower Manhattan, near City Hall:

lat = 40.7128
lng = -74.0060

The primary accepted coordinate envelope is lat ∈ [18, 72], lng ∈ [-180, -65] (lower 48, Alaska, Hawaii, US territories). The Western Aleutians additionally accept lat ∈ [51, 54], lng ∈ [172, 180). Anything outside those two regions returns 400 coord_out_of_bounds.

Starting from an address?

If your user typed an address, you do not need to resolve it first — /v1/fetch and /v1/ask both accept an address in place of lat/lng, and hand back the same quality information in a geocode block. Use POST /v1/geocode when you want the coordinate on its own — to inspect before spending a fetch, or to reuse across calls:

curl -s https://api.mireye.com/v1/geocode \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"address": "350 5th Ave, New York, NY 10118"}' | jq

{
  "lat": 40.748377,
  "lng": -73.984854,
  "accuracy_type": "rooftop",
  "normalized_address": "350 5th Ave, New York, NY 10118",
  "provider": "geocodio"
}

Check accuracy_type before you use the coordinate: rooftop is on the parcel, range_interpolation is an estimate along the street and can be kilometres off in rural areas. Details on the geocode page.

2. Get a token

/v1/ask and /v1/fetch require a bearer token. Sign in at www.mireye.com, create an API token in account settings, and export it:

export MIREYE_API_TOKEN="<paste from dashboard>"

See Authentication for the other credential paths (device-flow login for the local MCP adapter, OAuth for the hosted MCP endpoint).

3. Ask a question

curl -s https://api.mireye.com/v1/ask \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "question": "What is the elevation here?"
  }' | jq

Response:

{
  "lat": 40.7128,
  "lng": -74.006,
  "question": "What is the elevation here?",
  "answered_at": "2026-06-12T07:29:37.353451+00:00",
  "answer": "The ground elevation at coordinate 40.7128, -74.006 is 13.15 meters above sea level (NAVD88 datum), per USGS 3DEP/EPQS at ~10m resolution. This elevation is above the 10-meter storm-surge exposure threshold, though proximity to the coast would warrant further review in conjunction with flood zone and coastal distance data for a complete flood-risk assessment.",
  "confidence": "high",
  "citations": [
    {
      "source": "USGS_EPQS",
      "source_url": "https://epqs.nationalmap.gov/v1/json?x=-74.006&y=40.7128&wkid=4326&units=Meters",
      "fields": [
        "elevation"
      ],
      "fetched_at": "2026-06-12T07:29:40.330095+00:00",
      "confidence": "high"
    }
  ],
  "fields_used": [
    "elevation"
  ]
}

What just happened:

The planner (Claude Sonnet 4.6) read the question, looked at the field catalog, and decided only elevation was needed.
The terrain layer fetched 3DEP elevation for the coordinate.
The synthesizer (also Claude Sonnet 4.6) wrote the prose answer, grounded in the fetched value, and the citation engine attached the source.

Read the fields top-to-bottom: answer is the prose, confidence summarizes the whole response, citations is the audit trail, and fields_used lists exactly which catalog fields the answer depends on.

4. Fetch raw fields

When you know what you want, skip the planner and hit /v1/fetch:

curl -s https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "lat": 40.7128,
    "lng": -74.0060,
    "fields": ["elevation", "coast_distance_m"]
  }' | jq

Response:

{
  "lat": 40.7128,
  "lng": -74.006,
  "fetched_at": "2026-06-12T07:27:35.840477+00:00",
  "fields": {
    "elevation": {
      "value": 13.150006294,
      "unit": "meters",
      "source": "USGS_EPQS",
      "source_url": "https://epqs.nationalmap.gov/v1/json?x=-74.006&y=40.7128&wkid=4326&units=Meters",
      "confidence": "high",
      "fetched_at": "2026-06-12T07:27:35.826959+00:00",
      "dataset_vintage": "3DEP dynamic service",
      "ttl_seconds": 31536000,
      "notes": null
    },
    "coast_distance_m": {
      "value": 764.2256402243065,
      "unit": "meters",
      "source": "NOAA_CUSP",
      "source_url": "https://shoreline.noaa.gov/data/datasheets/cusp.html",
      "confidence": "high",
      "fetched_at": "2026-06-12T07:27:35.839783+00:00",
      "dataset_vintage": null,
      "ttl_seconds": 31536000,
      "notes": null
    }
  },
  "partial_failures": []
}

Each field is a self-contained record with provenance inline. The partial_failures array is empty here; on a call where the LCMS source times out, that field gets moved to partial_failures with retryable: true and the rest of the call still returns 200. Skip the field list entirely and use a preset for common workflows:

curl -s https://api.mireye.com/v1/fetch \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"lat": 40.7128, "lng": -74.0060, "preset": "flood_risk"}' | jq '.fields | keys'

[
  "coast_distance_m",
  "elevation",
  "intersects_nhd_area",
  "intersects_wetland",
  "nearest_waterbody_name",
  "nearest_wetland_distance_m",
  "surface_water_permanence_pct",
  "wetland_acres",
  "wetland_subtype",
  "wetland_type",
  "wetlands_within_100m_count",
  "wetlands_within_500m_count",
  "within_floodplain_polygon"
]

All presets and their field expansions are listed at /api-reference/fetch.

5. Use it from Claude Code

If you previously configured a local stdio server named mireye-earth, remove it first:

claude mcp remove mireye-earth -s user

Add the hosted MCP endpoint:

claude mcp add --transport http --scope user mireye-earth https://api.mireye.com/mcp

Restart Claude Code, run /mcp, and complete the browser sign-in flow. Seven tools are then available: mireye_ask, mireye_proximity, mireye_fetch, mireye_geocode, mireye_lookup, mireye_request_field, and mireye_field_request_status. Ask Claude:

“What’s the elevation at 40.7128, -74.0060?”

Claude will call mireye_ask, get the cited answer back, and surface the citation in chat. See /mcp/installation for Cursor and custom-agent setup.

6. Self-discover the catalog

Long-lived clients (agents, services) should fetch the catalog once at startup and cache it for an hour. This endpoint is public — no token needed:

curl -i https://api.mireye.com/v1/meta/fields | head -20

The response sets ETag and Cache-Control: public, max-age=3600. Subsequent requests with If-None-Match: "<etag>" return 304. See /api-reference/meta-fields for the full flow.

What’s next

POST /v1/ask

The natural-language endpoint. Two-model planner + synthesizer.

POST /v1/fetch

Fields, presets, and partial_failures semantics.

MCP tools

mireye_ask vs mireye_fetch from an agent’s perspective.

POST /v1/ask/stream

Same answer, first tokens in about five seconds.

Pricing and credits

What each call costs, and how to quote a job first.

POST /v1/runs

Screen thousands of locations in one job.

​1. Pick a coordinate

​Starting from an address?

​2. Get a token

​3. Ask a question

​4. Fetch raw fields

​5. Use it from Claude Code

​6. Self-discover the catalog

​What’s next