SatQuery AI API

Validates the inputs, classifies the query, plans and runs the specialist tools, and returns the grounded answer. Content type: multipart/form-data.

Tool parameters cannot be passed freely — the controller sets them within the permitted ranges published in the tool registry.

Runs only the geo-validator: per-file checks (format, CRS, bands, grid, acquisition time, no-data) and, for two files, pair checks (footprint IoU, co-registration offset, modality pairing, time gap). Returns the inferred mode.

curl -X POST "http://localhost:8050/v1/validate" -F "images=@HYD_S2L2A_20250107_T44QKE.tif" -F "images=@MUM_S1RTC_20250107_VVVH.tif"
# → { "valid": false, "pair": { "status": "fail", "summary": "Pair rejected — the images do not describe the same area.", ... } }

Lists every registered tool with its version, role, supported tasks and permitted parameter ranges. The same registry drives planning, so the trace can always be matched back to it.

{
  "id": "req_7f3k2q9d",
  "object": "analysis",
  "created": "2026-09-26T10:41:07Z",
  "query": "Highlight the water body referred to in the query.",
  "input": {
    "mode": "single",
    "images": [
      {
        "slot": "A",
        "name": "HYD_S2L2A_20250107_T44QKE.tif",
        "format": "GeoTIFF",
        "sensor": "Sentinel-2 MSI",
        "modality": "optical",
        "crs": "EPSG:32644",
        "size_px": [702, 786],
        "resolution_m": 10,
        "acquired": "2025-01-07T05:11:19Z"
      }
    ],
    "compatibility": null
  },
  "task": "grounding",
  "task_label": "Text-guided region grounding",
  "status": "completed",
  "answer": "**Grounded: Hussain Sagar Lake** — the single large water body in the scene. Area 410.9 ha …",
  "confidence": 0.95,
  "confidence_parts": {
    "model_likelihood": 0.94,
    "cross_tool_agreement": 0.97,
    "input_quality": 0.99
  },
  "evidence": [
    {
      "id": "hyd-lake",
      "type": "polygon",
      "label": "Hussain Sagar Lake",
      "confidence": 0.96,
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [78.46717, 17.43529],
            [78.46726, 17.43515],
            /* … 39 more coordinates */
          ]
        ]
      },
      "pixel_bbox": [245.5, 333.2, 502.8, 622.8],
      "stats": {
        "area": "410.9 ha (4.11 km²)",
        "perimeter": "12.8 km"
      }
    }
  ],
  "overlays": [],
  "charts": ["hyd-spectral", "hyd-composition"],
  "execution_trace": [
    {
      "step": 1,
      "stage": "validate",
      "tool": "geo-validator",
      "version": "1.2.0",
      "params": {
        "files": 1,
        "formats": "TIFF",
        "crs": "EPSG:32644"
      },
      "output": "1/1 file valid · GeoTIFF EPSG:32644 6×uint16 (optical)",
      "duration_ms": 280,
      "status": "done"
    },
    {
      "step": 2,
      "stage": "route",
      "tool": "agent-controller",
      "version": "1.1.0",
      "params": {
        "mode": "single",
        "modalities": "optical",
        "min_intent_confidence": 0.55
      },
      "output": "task = grounding (0.97) · target = “water body”",
      "duration_ms": 360,
      "status": "done"
    },
    {
      "step": 4,
      "stage": "execute",
      "tool": "rs-grounder",
      "version": "0.9.0",
      "params": {
        "text": "the water body",
        "box_threshold": 0.35,
        "top_k": 3,
        "refine": "spectral"
      },
      "output": "2 candidate regions · top score 0.93",
      "duration_ms": 820,
      "status": "done"
    }
  ],
  "models": ["geo-validator@1.2.0", "agent-controller@1.1.0", "rs-grounder@0.9.0", "spectral-indices@1.0.0", "satquery-vlm@1.2.0", "report-builder@1.0.0"],
  "reports": {
    "pdf": "/v1/reports/7f3k2q9d.pdf",
    "geojson": "/v1/reports/7f3k2q9d.geojson",
    "json": "/v1/reports/7f3k2q9d.json"
  }
}

{
  "status": "rejected",
  "error": { "code": "INCOMPATIBLE_PAIR", "message": "No overlap — footprints are 620 km apart (IoU 0.00)" },
  "execution_trace": [
    { "step": 1, "stage": "validate", "tool": "geo-validator", "status": "failed" },
    { "step": 2, "stage": "route", "tool": "agent-controller", "output": "task = rejected · no specialist tools executed" }
  ]
}

See the guardrail live in the mismatched-pair scene.