> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vangrid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Embodied AI

> Continuous spatial ground truth for robots and physical agents.

> [!NOTE]
>
> The API is in early access and is not publicly available. Endpoint URLs, request examples and sample responses on this page are illustrative. Contact [hello@vangrid.io](mailto:hello@vangrid.io) to request access.

Embodied AI systems, humanoid robots, drone swarms, autonomous industrial equipment, require a persistent, continuously updated model of the physical world to operate safely and effectively. Vangrid supplies the spatial cortex: a real-time stream of verified ground truth observations from the network that your system can ingest to keep its world model current.

## What embodied AI needs from spatial data

A world model is only as good as its inputs. Vangrid addresses three core requirements:

* **Continuous updates**, the physical world changes constantly; your world model must too
* **Verified observations**, every data point carries a `provenance_hash` so your system can trust what it receives
* **High spatial density**, tactical urban coverage means enough node overlap to corroborate observations and eliminate false positives

## Streaming spatial updates into your world model

Use the Vangrid Streaming API to subscribe to a geographic zone and receive push updates as ground truth changes.

**1. Define your area of interest**

Specify the geographic polygon your system operates within. Keep the AOI tight to reduce update volume and latency.

**2. Open a streaming connection**

Connect to the streaming endpoint with your API key. Updates arrive as newline-delimited JSON.

**3. Ingest updates into your world model**

Parse each event and update your spatial representation. Use `ground_truth_score` to weight observations.

**4. Verify provenance on critical observations**

For safety-critical decisions, verify the `provenance_hash` before acting on an observation.

```python Python theme={"dark"}
import requests
import json

API_KEY = "your-api-key"
BASE_URL = "https://api.vangrid.io/v1"

aoi = {
  "type": "Polygon",
  "coordinates": [[
    [-122.4194, 37.7749],
    [-122.4094, 37.7749],
    [-122.4094, 37.7849],
    [-122.4194, 37.7849],
    [-122.4194, 37.7749]
  ]]
}

with requests.post(
    f"{BASE_URL}/spatial/stream",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"aoi": aoi, "min_ground_truth_score": 0.80},
    stream=True
) as response:
    for line in response.iter_lines():
        if line:
            event = json.loads(line)
            # Ingest into world model
            update_world_model(event)
```

## Key data fields for embodied AI

Each streaming event includes:

| Field | Type | Description |
| - | - | - |
| `geometry` | GeoJSON | Location and shape of the observed feature |
| `ground_truth_score` | float (0–1) | Multi-node corroboration confidence |
| `timestamp` | ISO 8601 | When the observation was captured |
| `provenance_hash` | string | Cryptographic proof of data origin |
| `node_count` | integer | Number of edge nodes that contributed |
| `observation_type` | string | Category of observation (obstacle, occupancy, change) |

> [!TIP]
>
> For real-time navigation, filter to `ground_truth_score >= 0.75`. For safety-critical actions (grasping, human interaction), require `ground_truth_score >= 0.90`.

## Example streaming event

```json theme={"dark"}
{
  "event_id": "evt_8f3a2c1d",
  "timestamp": "2026-05-22T10:14:33.412Z",
  "geometry": {
    "type": "Point",
    "coordinates": [-122.4150, 37.7800]
  },
  "observation_type": "obstacle",
  "ground_truth_score": 0.94,
  "node_count": 12,
  "provenance_hash": "sha256:a3f8e2c1b4d7f9e0a2b5c8d1e4f7a0b3c6d9e2f5"
}
```

> [!NOTE]
>
> Contact [hello@vangrid.io](mailto:hello@vangrid.io) to discuss high-frequency streaming rates and dedicated node allocation for production embodied AI deployments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.