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

# POST /v1/ingest — Data Ingestion API Reference

> POST /v1/ingest — Submit spatial observations from your sensors into the Vangrid network to enrich ground truth and receive cryptographic provenance records.

<Note>
  All endpoint URLs, request examples, and sample responses on this page are illustrative. The Vangrid API is not yet publicly available — [contact us](mailto:hello@vangrid.io) to join early access.
</Note>

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.

<Info>
  Observations are an output of Vangrid's pipeline, not an input. Send video; Vangrid handles the rest.
</Info>

## How it works

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

## Endpoint

```text theme={null}
POST https://api.vangrid.io/v1/ingest
```

## Request

### Headers

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

### Body parameters

<ParamField body="video" type="file" required>
  Raw video file from your sensor. Supported formats: `mp4`, `mov`, `avi`. Maximum file size: 2 GB.
</ParamField>

<ParamField body="sensor_id" type="string">
  Your internal sensor identifier. Stored with the provenance record for every observation extracted from this video.
</ParamField>

<ParamField body="captured_at" type="string" required>
  ISO 8601 UTC timestamp of when the video capture began.
</ParamField>

<ParamField body="location_hint" type="object">
  Optional GeoJSON Point indicating the approximate capture location. Helps the pipeline georeferencing step if GPS metadata is missing from the video file.
</ParamField>

### Example request

```bash theme={null}
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

<ResponseField name="ingestion_id" type="string">
  Unique identifier for this ingestion job. Use this to poll processing status.
</ResponseField>

<ResponseField name="status" type="string">
  Current pipeline status. One of: `queued`, `processing`, `complete`, `failed`.
</ResponseField>

<ResponseField name="estimated_completion" type="string">
  ISO 8601 UTC timestamp of estimated processing completion.
</ResponseField>

### Example response

```json theme={null}
{
  "ingestion_id": "ing_7c4d1e8b",
  "status": "queued",
  "estimated_completion": "2026-05-22T10:16:00.000Z"
}
```

<Tip>
  Once processing is `complete`, the extracted observations are available via the [spatial query endpoint](/api/spatial-queries) and include `provenance_hash` values you can verify using the [provenance verification endpoint](/data/cryptographic-provenance).
</Tip>

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