API Reference

Base URL: http://localhost:8080/api/v1 (default).

---

GET /health

Checks the liveness status of the service and reports the current VLM backend state.

Response

{
  "status": "healthy",
  "service": "semantic-search-agent",
  "version": "2026.1.0",
  "vlm_backend": "ovms",
  "vlm_status": "connected",
  "uptime_seconds": 42.5
}

Field	Type	Description
status	string	Always "healthy" when the service is running.
service	string	Service name.
version	string	Service version.
vlm_backend	string	Configured VLM backend (ovms, openvino_local, openai).
vlm_status	string	"connected" if the backend is available, otherwise "unavailable".
uptime_seconds	float	Seconds since the service started.

---

POST /compare/order

Compares a list of expected items against detected items to identify missing, extra, and quantity-mismatched products. Uses the configured matching strategy (exact, semantic, or hybrid).

Request Body (JSON)

Parameter	Type	Required	Description
expected_items	array of ItemModel	Yes	Items that should be present with their expected quantities.
detected_items	array of ItemModel	Yes	Items detected by the vision pipeline.
options	ComparisonOptions	No	Optional matching behavior overrides.

ItemModel

Field	Type	Required	Description
name	string	Yes	Item name.
quantity	integer	Yes	Item quantity (≥ 1).

ComparisonOptions

Field	Type	Default	Description
use_semantic	boolean	true	Enable semantic matching for items not matched exactly.
exact_match_first	boolean	true	Try exact match before semantic (always true in engine).
case_insensitive	boolean	true	Case-insensitive text normalization.

Examples

Basic Order Validation:

curl -X POST http://localhost:8080/api/v1/compare/order \
  -H "Content-Type: application/json" \
  -d '{
    "expected_items": [
      {"name": "apple", "quantity": 3},
      {"name": "milk", "quantity": 2},
      {"name": "bread", "quantity": 1}
    ],
    "detected_items": [
      {"name": "apple", "quantity": 3},
      {"name": "whole milk", "quantity": 2},
      {"name": "orange juice", "quantity": 1}
    ]
  }'

Response

{
  "status": "mismatch",
  "validation": {
    "missing": [
      {"name": "bread", "quantity": 1}
    ],
    "extra": [
      {"name": "orange juice", "quantity": 1}
    ],
    "quantity_mismatch": [],
    "matched": [
      {
        "expected": {"name": "apple", "quantity": 3},
        "detected": {"name": "apple", "quantity": 3},
        "match_type": "exact",
        "confidence": 1.0
      },
      {
        "expected": {"name": "milk", "quantity": 2},
        "detected": {"name": "whole milk", "quantity": 2},
        "match_type": "hybrid_semantic",
        "confidence": 0.92
      }
    ]
  },
  "metrics": {
    "total_expected": 3,
    "total_detected": 3,
    "exact_matches": 1,
    "semantic_matches": 1,
    "processing_time_ms": 245.3
  }
}

Field	Type	Description
status	string	"validated" if all items matched, "mismatch" otherwise.
validation.missing	array	Expected items with no detected match.
validation.extra	array	Detected items with no expected match.
validation.quantity_mismatch	array	Items where names matched but quantities differ.
validation.matched	array	Successfully matched item pairs with match type and confidence.
metrics.exact_matches	integer	Count of items resolved by exact string matching.
metrics.semantic_matches	integer	Count of items resolved by semantic VLM matching.
metrics.processing_time_ms	float	Total processing time in milliseconds.

---

POST /compare/inventory

Checks whether a list of item names exist in the inventory, using exact or semantic matching.

Request Body (JSON)

Parameter	Type	Required	Description
items	array of strings	Yes	Item names to look up in inventory.
inventory	array of strings	No	Explicit inventory list. Uses config/inventory.json if omitted.
options	ComparisonOptions	No	Optional matching behavior overrides (same as /compare/order).

Examples

Inventory Check:

curl -X POST http://localhost:8080/api/v1/compare/inventory \
  -H "Content-Type: application/json" \
  -d '{
    "items": ["apple", "cola bottle", "bread loaf"],
    "inventory": ["apple", "coca cola 500ml", "bread", "milk"]
  }'

Response

{
  "results": [
    {
      "item": "apple",
      "match": true,
      "matched_inventory_item": "apple",
      "match_type": "exact",
      "confidence": 1.0
    },
    {
      "item": "cola bottle",
      "match": true,
      "matched_inventory_item": "coca cola 500ml",
      "match_type": "hybrid_semantic",
      "confidence": 0.91
    },
    {
      "item": "bread loaf",
      "match": true,
      "matched_inventory_item": "bread",
      "match_type": "hybrid_semantic",
      "confidence": 0.88
    }
  ],
  "summary": {
    "total_items": 3,
    "matched": 3,
    "unmatched": 0,
    "processing_time_ms": 312.7
  }
}

---

POST /compare/semantic

Performs a generic semantic comparison between two arbitrary text strings using the configured VLM backend.

Request Body (JSON)

Parameter	Type	Required	Description
text1	string	Yes	First text string (treated as the “expected” item).
text2	string	Yes	Second text string (treated as the “detected” item).
context	string	No	Domain context passed to the VLM prompt. Default: "grocery products".

Examples

Semantic Comparison:

curl -X POST http://localhost:8080/api/v1/compare/semantic \
  -H "Content-Type: application/json" \
  -d '{
    "text1": "green apple",
    "text2": "apple",
    "context": "grocery products"
  }'

Response

{
  "match": true,
  "confidence": 0.92,
  "reasoning": "YES",
  "match_type": "semantic"
}

Field	Type	Description
match	boolean	true if the VLM determined the texts refer to the same item.
confidence	float	Confidence score between 0.0 and 1.0.
reasoning	string	Raw VLM response (YES or NO) or cache/error details.
match_type	string	Always "semantic" for this endpoint.

---

GET /metrics

Prometheus-compatible metrics endpoint. Available on port 9090 by default (configurable via METRICS_PORT).

curl http://localhost:9090/metrics

Key metrics exposed:

Metric	Type	Description
api_requests_total	Counter	Total requests per endpoint, method, and status code.
matches_total	Counter	Total match operations per match type and result.
request_duration_seconds	Histogram	Request latency per endpoint and method.
vlm_inference_duration_seconds	Histogram	VLM inference latency per backend.
cache_hits_total	Counter	Total cache hits per operation type.
cache_misses_total	Counter	Total cache misses per operation type.
vlm_backend_available	Gauge	VLM backend availability (1 = available, 0 = unavailable).