POST /v1/ingest — Data Ingestion API Reference

All endpoint URLs, request examples, and sample responses on this page are illustrative. The Vangrid API is not yet publicly available — contact us to join early access.

The data ingestion endpoint accepts raw video footage from your sensor systems. You do not submit observations directly — Vangrid’s pipeline ingests the video and extracts spatial observations (objects, vehicles, structures, etc.) automatically. The resulting observations are processed through the same cryptographic provenance pipeline as native edge node data.

Observations are an output of Vangrid’s pipeline, not an input. Send video; Vangrid handles the rest.

How it works

You submit video — Upload a raw video clip from your sensor (drone, fixed camera, vehicle-mounted, etc.)
Vangrid processes it — The pipeline runs perception, georeferencing, and quality checks on the footage
Observations are extracted — Spatial observations (geometry, type, confidence) are produced and committed to the network
You receive provenance records — Each extracted observation gets a provenance_hash you can use to verify integrity later

Endpoint

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

Request

Headers

Header	Value
`Authorization`	`Bearer your-api-key`
`Content-Type`	`multipart/form-data`

Body parameters

video

file

required

Raw video file from your sensor. Supported formats: mp4, mov, avi. Maximum file size: 2 GB.

sensor_id

string

Your internal sensor identifier. Stored with the provenance record for every observation extracted from this video.

captured_at

string

required

ISO 8601 UTC timestamp of when the video capture began.

location_hint

object

Optional GeoJSON Point indicating the approximate capture location. Helps the pipeline georeferencing step if GPS metadata is missing from the video file.

Example request

curl -X POST https://api.vangrid.io/v1/ingest \
  -H "Authorization: Bearer your-api-key" \
  -F "video=@/path/to/footage.mp4" \
  -F "sensor_id=drone-unit-07" \
  -F "captured_at=2026-05-22T10:14:30.000Z" \
  -F 'location_hint={"type":"Point","coordinates":[-122.4150,37.7800]}'

Response

Once the video is accepted, Vangrid returns an ingestion_id you can use to track processing status. Observations are not immediately available — pipeline processing typically takes 30–120 seconds depending on video length.

Response fields

ingestion_id

string

Unique identifier for this ingestion job. Use this to poll processing status.

status

string

Current pipeline status. One of: queued, processing, complete, failed.

estimated_completion

string

ISO 8601 UTC timestamp of estimated processing completion.

Example response

{
  "ingestion_id": "ing_7c4d1e8b",
  "status": "queued",
  "estimated_completion": "2026-05-22T10:16:00.000Z"
}

Once processing is complete, the extracted observations are available via the spatial query endpoint and include provenance_hash values you can verify using the provenance verification endpoint.

Error responses

Status	Error code	Description
`400`	`unsupported_format`	Video format not supported
`400`	`missing_timestamp`	`captured_at` is required
`400`	`file_too_large`	Video exceeds 2 GB limit
`401`	`unauthorized`	Missing or invalid API key
`429`	`rate_limit_exceeded`	Too many requests

​How it works

​Endpoint

​Request

​Headers

​Body parameters

​Example request

​Response

​Response fields

​Example response

​Error responses

How it works

Endpoint

Request

Headers

Body parameters

Example request

Response

Response fields

Example response

Error responses