DocsAPI reference

Data ingestion

Send your own footage to POST /v1/ingest and get back a provenance record for each extracted observation.

This API is currently in early access and has not been opened to the public. Treat the endpoint URLs, request samples and response examples throughout this page as illustrative only. To get access, email hello@utopiadata.net.

Raw video from your sensor systems is what the ingestion endpoint takes in. Rather than submitting observations yourself, you hand over footage and Utopia's pipeline does the extraction, pulling out spatial observations like objects, vehicles and structures on its own. Whatever the pipeline extracts passes through the identical cryptographic provenance process that native edge node data goes through.

Think of observations as what Utopia's pipeline produces, never as something you supply. Your job is to send video; everything after that is handled for you.

How it works #

You submit video

Send a raw clip from any sensor you operate, be it a drone, a stationary camera or a rig mounted on a vehicle.

Utopia processes it

Perception, georeferencing and quality checks are applied to the footage by the pipeline.

Observations are extracted

The pipeline generates spatial observations, complete with geometry, type and confidence, and commits them to the network.

You receive provenance records

Every observation that comes out carries a provenance_hash, which lets you verify its integrity down the line.

Endpoint #

POST https://api.utopiadata.net/v1/ingest

Request #

Headers #

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

Body parameters #

videofilerequired

The raw sensor video. Accepted formats: mp4, mov and avi. Files may be up to 2 GB.

sensor_idstringrequired

An identifier of your own choosing for the sensor. It is recorded in the provenance record of each observation extracted from the video.

captured_atISO 8601 timestamprequired

The UTC time at which recording of the video started.

location_hintGeoJSON Point

A rough capture location, provided optionally. When the video file lacks GPS metadata, this helps the pipeline's georeferencing step.

Example request #

curl -X POST https://api.utopiadata.net/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 #

When Utopia accepts the video, it hands back an ingestion_id for tracking the job. The observations themselves take a while to appear; depending on the length of the video, the pipeline usually needs 30 to 120 seconds.

Response fields #

ingestion_idstring

The identifier for this ingestion job. Poll with it to check processing status.

statusstring

Where the job stands in the pipeline: queued, processing, complete or failed.

estimated_completionISO 8601 timestamp

When processing is expected to be done.

Example response #

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

After processing finishes, the extracted observations can be retrieved via the spatial query endpoint. Each carries a provenance_hash, and the provenance verification endpoint lets you check those hashes.

Error responses #

Status	Error code	Description
400	unsupported_format	The video is in a format we do not accept
400	missing_timestamp	The captured_at field must be provided
400	file_too_large	The video is over the 2 GB cap
401	unauthorized	API key absent or not valid
429	rate_limit_exceeded	Request volume exceeded your limit

PreviousSpatial queries NextStreaming