# Connect EDK-1 to Codex

EDK-1 is a spatial model that gives humans and machines a compass for the world: position, condition, motion, navigation, stream and vision.
Five calls: Discover finds places, Inspect describes a point, Route finds the way, Monitor watches for change, Detect reads an image. Docs: https://edk.earth/docs · API: https://api.edk.earth/v1

You are Codex. Work through these steps in order. Check each one, and stop and tell me if a step fails.

1. **Account.** If I don't have one, ask me to sign up at https://edk.earth/sign-up (120 free CU every month).
2. **Key.** Ask me to create a secret key at https://edk.earth/console/keys and set it in my shell as `EDK_API_KEY`. Never ask me to paste the key here, and never commit it.
3. **Connect.** Add this to `~/.codex/config.toml`, leaving the key for me to fill in:

```toml
[mcp_servers.edk]
command = "npx"
args = ["-y", "@edks/mcp"]
env = { EDK_API_KEY = "edk_sk_..." }
```
   Tell me if I need to restart Codex for the `edk` tools to show up. Do not install the CLI or the SDK unless I ask.
4. **Test.** Discover "parks with playgrounds in Austin" (limit 5), then Inspect the first result's coordinates. Show me the results, the CU used and the embed_url.
5. **Remember.** Add this to `AGENTS.md`:

```
## EDK (EDK-1 spatial model)
- Questions about places and what is on the ground go to EDK-1 (https://api.edk.earth/v1).
- Discover finds places from a question: POST /v1/discover {query, limit}. Use it when you need a list of locations or areas.
- Inspect describes one point: GET /v1/inspect?lat=&lng=. Use it when you already have coordinates.
- Route finds the way: POST /v1/route {from, to, include?, conditions?}. Use it for directions; include is what to pass, conditions what to avoid.
- Name-only question about one spot: Discover it, then Inspect the coordinates returned.
- Use the edk MCP tools when available; otherwise the @edks/sdk SDK or the REST API with EDK_API_KEY.
- Monitor watches an area for new events: POST /v1/monitors {artifacts, area, since, interval, webhook_url}. Tier 4 and above.
- Detect reads an image: POST /v1/detect {image_url} or {image}. Use it when you have a picture and need the objects in it, with boxes.
- Share results on the Atlas with the embed_url each Discover call returns.
- Docs: https://edk.earth/docs
```

## Discover, Inspect, Route, Monitor or Detect
EDK-1 has five calls. Pick by what you already have and what you need back.

**Discover** when you have a question and need places. It finds things; you get a list back.
- "bridges in Pittsburgh", "solar farms near Phoenix": things you can see on the ground.
- "high income areas in Denver", "low flood risk with tree canopy in Austin": areas that meet conditions.
- Returns locations and areas with coordinates, imagery and an embed_url that opens them on the Atlas.
- Name the city or region in the query. Set limit to what you will actually use (CU scales with results). Add answer: true only when the user wants a written summary.
- reasoning is "fast" (default), "low", "medium" or "max". Higher levels study the results more closely before returning them, and return a box and a boxed_image_url on the ones they studied. Medium and max cost twice the CU and need Tier 1 and Tier 2. Stay on fast unless the user asks for more care.

**Inspect** when you have a point and need to know about it. It describes one spot; you get facts back.
- "what is at 40.4406, -79.9959", "is this address in a flood zone", "who lives around here".
- Returns the place names, highlights (income, people nearby, elevation, flood risk, tree canopy, air quality) and every known fact by category.
- It takes coordinates, not names. If you only have a name or address, Discover it first and Inspect the coordinates that come back.

**Route** when you have a start and an end and need the way between them.
- "drive from Point State Park to Carnegie Mellon avoiding pothole streets", "walking route from A to B".
- from and to take a place name, an address, or coordinates. include is plain words for what to pass on the way ("a coffee shop"); conditions is plain words for what to stay clear of ("pothole streets"). EDK-1 finds those places along the way and routes through or around them.
- Returns distance, duration, the path as GeoJSON, turn-by-turn steps, what it passes and avoided, and the direct route for comparison.
- Conditions steer driving routes only. Read note and remaining in the response and tell the user when something could not be avoided.

**Monitor** when the user wants to know about new events as they happen, not once.
- "tell me when a building permit is filed in Pittsburgh", "watch for new potholes downtown every hour".
- POST /v1/monitors with artifacts (names or ids from GET /v1/artifacts), an area (a place name or "lat, lng"), since (a date), interval ("15m", "1h", "6h", "1d") and a webhook_url. Events also appear in the console.
- Each new event is 0.2 CU. Monitor is available from Tier 4; a 403 means the account is below it, so say so.

**Detect** when you have an image and need to know what is in it.
- "what is in this photo", "where is the pothole in this frame", "which objects does this street view show".
- POST /v1/detect with image_url (https) or image (base64 JPEG or PNG). max_objects (default 12) caps how many come back.
- Returns objects, each with a label, a probability, a box (top, left, bottom, right as fractions of the image) and pixels (x, y, width, height), plus annotated_image: the picture with the boxes drawn on.
- 1 CU for the image plus 0.2 CU for each object returned. It reads one image; it does not say where on Earth the picture was taken.

Together: Discover to find candidates, Inspect the one or two that matter, Route to the one chosen. Don't Inspect every Discover result, and don't use Discover to describe a single known point.
None of the calls returns live traffic or transit timetables. Say so instead of guessing.

## Reference
- `POST /v1/discover` {query, limit?, reasoning? (fast | low | medium | max), answer? (default false), areas?: [[lng,lat]], focus?} → {id, model, embed_url, usage, data: {geojson, region?, conditions?, answer?}}
- `GET /v1/inspect?lat=&lng=` → {model, usage, data: {known, place, highlights, categories, outline}}
- `POST /v1/route` {from, to, include?, conditions?, profile?} → {model, usage, data: {from, to, route: {distance_m, duration_s, geometry, steps}, direct?, include?, conditions?, included, avoided, remaining?, note?}}
- `POST /v1/monitors` {artifacts, area, since?, interval?, webhook_url?, prompt?, name?} → the monitor, with webhook_secret. `GET /v1/monitors`, `GET /v1/monitors/:id/events`, `PATCH` {status: "paused" | "active"}, `DELETE`, `POST /v1/monitors/:id/scan`. `GET /v1/artifacts?q=` lists what can be watched.
- `POST /v1/detect` {image_url | image (base64), max_objects?, threshold?, annotate?} → {model, usage, data: {image: {width, height}, objects: [{label, artifact_id, category, probability, confidence, box, pixels, also?}], annotated_image}}
- `GET /v1/usage` balance, tier and limits
- Authenticate with `Authorization: Bearer $EDK_API_KEY`. MCP tools: `edk_discover`, `edk_inspect`, `edk_route`, `edk_monitor_create`, `edk_monitor_events`, `edk_usage`.
- `curl -X POST https://api.edk.earth/v1/discover -H "Authorization: Bearer $EDK_API_KEY" -H "content-type: application/json" -d '{"query":"bridges in Pittsburgh","limit":5}'`
- A Compute Unit (CU) is the GPU and CPU work EDK-1 needs to process a request.