Quickstart

Create the quantity your device measures. Note the returned id (mdef_…).

curl -X POST "$AEROVY_API/v2/definitions/metrics" \
  -H "X-Api-Key: $AEROVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "soc",
    "displayName": "State of Charge",
    "dataType": "Double",
    "defaultAggregation": "Last",
    "unitLabel": "%"
  }'

Tie your metric(s) into a device type. Note the returned stable type id (tdefi_…).

curl -X POST "$AEROVY_API/v2/definitions/thing-types" \
  -H "X-Api-Key: $AEROVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Battery",
    "metricIds": ["mdef_<soc>"]
  }'

A device needs a Place to live in. Create a Site and note its id (<siteId>).

curl -X POST "$AEROVY_API/v2/sites" \
  -H "X-Api-Key: $AEROVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "siteName": "Depot 1",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "address": "1 Market St, San Francisco, CA"
  }'

Create the device in that Site, referencing the type from step 2. Note its id (<thingId>).

curl -X POST "$AEROVY_API/v2/sites/<siteId>/things" \
  -H "X-Api-Key: $AEROVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "thingName": "Battery A1",
    "thingType": "Battery",
    "thingTypeId": "tdefi_<battery>"
  }'

POST telemetry for the Thing. The body is a batch of frames: each frame has a timestamp (Unix epoch milliseconds) and a metrics map of metric name to value.

curl -X POST "$AEROVY_API/v2/thing/<thingId>/data" \
  -H "X-Api-Key: $AEROVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frames": [
      {
        "timestamp": 1718884800000,
        "metrics": { "soc": 87.4 }
      }
    ]
  }'

A successful call returns 200 OK with an ingest summary: the thingId, framesIngested, and the distinct metrics written.

Real payloads rarely match the frames shape. A Template maps an external payload onto your metrics, so you can ingest data in its native shape. Create a ThingData template with JSON Pointer mappings and note its id (tmpl_…).

curl -X POST "$AEROVY_API/v2/templates" \
  -H "X-Api-Key: $AEROVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Telemetry v1",
    "target": "ThingData",
    "format": "JsonPointer",
    "spec": {
      "recordsPointer": "/readings",
      "timestamp": { "source": { "pointer": "/ts" }, "format": "iso8601" },
      "mappings": [
        { "metricId": "mdef_<soc>", "source": { "pointer": "/soc" } }
      ]
    }
  }'

POST the raw external payload to the template-apply endpoint. The platform maps it through the template and writes the readings. Add ?previewOnly=true to validate the mapping without persisting.

curl -X POST "$AEROVY_API/v2/thing/<thingId>/data/template/<templateId>?previewOnly=false" \
  -H "X-Api-Key: $AEROVY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "readings": [
      { "ts": "2026-06-20T12:00:00Z", "soc": 87.4 }
    ]
  }'

The response is a processing report: records parsed, readings written, and any skipped records or fields. See Templates for the full mapping spec.