POST /v1/ingest — Data Ingestion API Reference

The data ingestion endpoint lets you contribute spatial observations from your own sensor systems into the Vangrid network. Submitted observations are processed through the same cryptographic provenance pipeline as native edge node data, giving you verifiable records of what your systems reported and when.

Endpoint

POST https://api.vangrid.io/v1/ingest

Request

Headers

Header	Value
`Authorization`	`Bearer your-api-key`
`Content-Type`	`application/json`

Body parameters

observations

array

required

Array of observation objects to submit. Maximum 500 observations per request.

Show Observation object fields

geometry

object

required

GeoJSON geometry (Point, Polygon, or LineString) of the observation.

observation_type

string

required

Type of observation. Must be one of: obstacle, occupancy, change, structure, vehicle, vegetation.

timestamp

string

required

ISO 8601 UTC timestamp of when the observation was captured by your sensor.

sensor_id

string

Your internal sensor identifier. Stored with the provenance record.

confidence

number

Your sensor’s confidence in the observation (0.0–1.0). Used as an input when computing the network ground_truth_score.

Example request

curl -X POST https://api.vangrid.io/v1/ingest \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "observations": [
      {
        "geometry": {
          "type": "Point",
          "coordinates": [-122.4150, 37.7800]
        },
        "observation_type": "vehicle",
        "timestamp": "2026-05-22T10:14:30.000Z",
        "sensor_id": "lidar-unit-42",
        "confidence": 0.88
      }
    ]
  }'

Response

Response fields

ingestion_id

string

Unique identifier for this ingestion batch.

accepted

integer

Number of observations successfully accepted.

rejected

integer

Number of observations rejected due to validation errors.

provenance_hashes

array

Array of provenance hash strings, one per accepted observation. Archive these for future verification.

errors

array

Details on any rejected observations, including index and reason.

Example response

{
  "ingestion_id": "ing_7c4d1e8b",
  "accepted": 1,
  "rejected": 0,
  "provenance_hashes": [
    "sha256:b7c3d9e1f4a6b8c0d2e5f7a9b1c4d6e8f0a2b4c6"
  ],
  "errors": []
}

Store each provenance_hash alongside the original observation in your own system. You can verify these hashes at any time using the provenance verification endpoint.

Error responses

Status	Error code	Description
`400`	`invalid_geometry`	One or more geometries are not valid GeoJSON
`400`	`invalid_observation_type`	Unknown observation type provided
`400`	`batch_too_large`	More than 500 observations in a single request
`401`	`unauthorized`	Missing or invalid API key
`429`	`rate_limit_exceeded`	Too many requests

Overview

Spatial API

POST /v1/ingest — Data Ingestion API Reference

Endpoint

Request

Headers

Body parameters

Example request

Response

Response fields

Example response

Error responses

Overview

Spatial API

Documentation Index

​Endpoint

​Request

​Headers

​Body parameters

​Example request

​Response

​Response fields

​Example response

​Error responses

Endpoint

Request

Headers

Body parameters

Example request

Response

Response fields

Example response

Error responses