> ## 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.

# Cryptographic Provenance: Verifying Spatial Data Integrity

> Every Vangrid observation includes a provenance_hash — cryptographic proof the data came from a real edge node at a specific time and has not been altered.

Every observation returned by the Vangrid API includes a `provenance_hash` — a SHA-256 digest that lets you verify, independently, that the data came from a legitimate Vangrid edge node, at the stated time, and has not been modified in transit or storage. This is critical for defense, compliance, and safety applications where data integrity is non-negotiable.

## What the provenance hash covers

The `provenance_hash` is computed over:

* The observation payload (geometry, classification, scores)
* The originating node's unique identifier
* The capture timestamp (UTC, millisecond precision)
* The Vangrid network epoch (a rotating network-wide nonce)

Any change to any of these inputs produces a completely different hash. If a hash you received matches the hash you compute from the payload, the data is authentic.

## Verifying a provenance hash

<Steps>
  <Step title="Retrieve the observation">
    Make a spatial query or read from a streaming event. Note the `provenance_hash` field.
  </Step>

  <Step title="Fetch the verification endpoint">
    Call `GET /v1/provenance/{provenance_hash}` with your API key to retrieve the signed verification record.
  </Step>

  <Step title="Compare the canonical hash">
    The response includes the canonical hash computed by the issuing node. Compare it to the hash in your observation.
  </Step>
</Steps>

```python Python theme={null}
import requests

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

def verify_provenance(provenance_hash: str) -> bool:
    response = requests.get(
        f"{BASE_URL}/provenance/{provenance_hash}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    if response.status_code == 200:
        record = response.json()
        return record["verified"] is True
    return False

# Example usage
is_valid = verify_provenance("sha256:a3f8e2c1b4d7f9e0a2b5c8d1e4f7a0b3c6d9e2f5")
print(f"Provenance valid: {is_valid}")
```

## Verification response

```json theme={null}
{
  "provenance_hash": "sha256:a3f8e2c1b4d7f9e0a2b5c8d1e4f7a0b3c6d9e2f5",
  "verified": true,
  "node_id": "node_7f3a",
  "captured_at": "2026-05-22T10:14:33.412Z",
  "network_epoch": "epoch_2026_05",
  "signature_algorithm": "ECDSA-P256"
}
```

<Warning>
  A `verified: false` result means the hash could not be matched in the Vangrid ledger. Do not use this observation for safety-critical decisions.
</Warning>

<Tip>
  Archive provenance hashes alongside your observations in your own storage. You can re-verify them at any time using the verification endpoint.
</Tip>