Edge device integration

Edge devices run detection at the inspection point and push results to the API. Edge endpoints use API key authentication and address containers by container number, not record ID.

Request bodies are JSON with a 50 MB limit. Send images as base64 JPEG, either raw or as a data: URL.

Send one request per scan session

Don’t send a request per frame. Track objects across frames, keep the highest-confidence detection for each tracked object, and submit once when the session ends. A session usually ends when no new objects appear for a few seconds, when OCR reads a different container, or when an operator completes the scan manually.

1. Identify the container

Send the container number once OCR has read it consistently across frames.

curl -sS -X POST https://api.cargovision.app/v1/edge/containers/identify \
  -H "X-API-Key: $CARGOVISION_EDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "container_number": "MSCU1234566",
    "image": "<base64 JPEG>",
    "confidence": 0.94,
    "camera_id": "gate-1-rear-ocr",
    "device_id": "jetson-gate-1",
    "user_email": "operator@example.com"
  }'

The response tells you whether the container is new:

{
  "success": true,
  "message": "Container created and identified",
  "data": {
    "containerId": "665f1c2e9b1e4a0012ab34cd",
    "containerNumber": "MSCU1234566",
    "isNewContainer": true,
    "imageUrl": "https://…",
    "status": "IDENTIFIED"
  }
}

2. Submit the defect scan

{
  "detections": [
    { "class_name": "dent", "confidence": 0.91, "box": { "x1": 0.12, "y1": 0.40, "x2": 0.25, "y2": 0.58 } },
    { "class_name": "hole", "confidence": 0.83, "box": { "x1": 0.61, "y1": 0.22, "x2": 0.66, "y2": 0.29 } }
  ],
  "box_format": "normalized_xyxy",
  "image": "<base64 JPEG>",
  "visualization": "<optional annotated base64 JPEG>",
  "camera_id": "gate-1-defect",
  "device_id": "jetson-gate-1"
}

• detections is required. Send an empty array for a clean scan.
• Send boxes as x1, y1, x2, y2. Set box_format to normalized_xyxy when coordinates are fractions of the frame size between 0 and 1.
• Send class_name, confidence, and box only. The API assigns severity, structural integrity, and the AI decision; any severity you send is ignored. See Inspection lifecycle.
• If the container hasn’t been identified yet, the API creates it.

3. Submit the category scan

The category scan carries segmentation results for the cargo. detections and image are required. Each detection can include polygon (x and y arrays), area_percentage, quantity, and volume. When the container has a manifest, the API checks the detected categories against it.

Report stream health

Send a stream event whenever a camera stream changes state so the dashboard can show stream health:

{
  "camera_id": "gate-1-defect",
  "device_id": "jetson-gate-1",
  "event_type": "RECONNECTING",
  "rtsp_url": "rtsp://camera.local/stream1",
  "model_key": "container_defect",
  "error_message": "Read timeout"
}

camera_id and event_type are required. event_type is one of STARTED, STOPPED, ERROR, or RECONNECTING. Credentials in rtsp_url are stripped before storage.

Handle failures

• 400 means the request will never succeed as sent. Fix the payload; don’t retry it unchanged.
• 401 means the API key is missing or wrong.
• 5xx and network errors are transient. Retry with backoff, and log locally instead of blocking inference.