API Documentation

Integration instructions for the low-latency image inference endpoint.

1Authentication

All API requests require an API key passed in the Authorization header. Generate keys from your dashboard.

Secret Keys (server-side only)

Authorization: Bearer hail_live_your_secret_key

Publishable Keys (frontend, origin-locked)

Authorization: Bearer hail_pub_your_publishable_key

Publishable keys are restricted to allowed origins configured in your dashboard. The browser's Origin header is validated automatically.

2Detection Endpoint

POST/api/v1/detect

Upload one or more images to detect hail dents and nozzles. Images must be sent as multipart/form-data with the field name image.

  • Supported Formats: JPEG, PNG, WebP
  • Max File Size: 10MB per image
  • Batch: Up to 10 images per request
  • Rate Limit: Depends on your available credits

Example cURL Request

curl -X POST https://hailapi.com/api/v1/detect \-H "Authorization: Bearer hail_live_your_api_key" \-F "image=@/path/to/car-hood.jpg"

Example SDK Request

import { HailAPI } from '@hailapi/client';

const hail = new HailAPI({ apiKey: 'hail_live_...' });

const result = await hail.detect(imageBuffer);
const { analysis, summary } = result.data[0].data;

3Response Schema

The API returns a batch array of results. Each result contains detections with bounding boxes, a summary, and an analysis object with damage scoring. Classes: 0 = Haildent, 1 = Nozzle. Severity levels: small, medium, large.

{
  "data": [
    {
      "data": {
        "detections": [
          {
            "id": "det_abc12345",
            "class": "Haildent",
            "class_id": 0,
            "confidence": 0.892,
            "bbox": { "x": 120, "y": 450, "width": 60, "height": 65 },
            "severity": "medium",
            "diameter_px": 62.5,
            "estimated_diameter_mm": 8.2
          }
        ],
        "summary": {
          "total_haildents": 5,
          "total_nozzles": 1,
          "processing_time_ms": 234
        },
        "analysis": {
          "by_severity": { "small": 2, "medium": 2, "large": 1 },
          "density": "moderate",
          "damage_score": 42,
          "calibrated": true,
          "calibration_note": "Calibrated via nozzle reference"
        },
        "image_info": { "width": 4032, "height": 3024 }
      }
    }
  ],
  "error": null
}

Key Fields

damage_scoreOverall damage score from 0 to 100
by_severityCount of detections by severity level (small/medium/large)
densitySpatial density: none, sparse, moderate, or dense
estimated_diameter_mmReal-world diameter estimate when a nozzle reference is present

4Error Responses

401Unauthorized

Missing or invalid API key.

402Payment Required

Insufficient credits. Purchase more from the dashboard.

403Forbidden

Origin not allowed for this publishable key.

429Too Many Requests

Burst limit reached.

400Bad Request

Invalid image format, size, or missing file.