API Reference#

Comprehensive REST API documentation for the Dine-In Order Accuracy service.

Base URL#

http://localhost:8083

Authentication#

Currently no authentication required (internal service).

Endpoints#

Health Check#

Check service health status.

GET /health

Response

{
  "status": "healthy",
  "timestamp": "2026-02-16T16:36:50.278369",
  "benchmark_mode": false
}

Validate Plate#

Validate a food plate image against an order manifest.

POST /api/validate

Request

Parameter	Type	Location	Description
`image`	file	form-data	Plate image (JPEG/PNG)
`order`	JSON string	form-data	Order manifest

Order Schema

{
  "order_id": "string",
  "table_number": "string",
  "restaurant": "string",
  "items": [
    {
      "name": "string",
      "quantity": 1
    }
  ],
  "modifiers": []
}

Example Request

curl -X POST "http://localhost:8083/api/validate" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@plate.jpg" \
  -F 'order={
    "order_id": "ORD-001",
    "table_number": "12",
    "restaurant": "Test Restaurant",
    "items": [
      {"name": "Burger", "quantity": 1},
      {"name": "Fries", "quantity": 1}
    ]
  }'

Response

{
  "validation_id": "uuid-string",
  "image_id": "ORD-001",
  "order_complete": true,
  "accuracy_score": 1.0,
  "missing_items": [],
  "extra_items": [],
  "quantity_mismatches": [],
  "matched_items": [
    {
      "expected_name": "Burger",
      "detected_name": "Hamburger",
      "similarity": 0.92,
      "quantity": 1
    },
    {
      "expected_name": "Fries",
      "detected_name": "French Fries",
      "similarity": 0.95,
      "quantity": 1
    }
  ],
  "timestamp": "2026-02-16T16:36:50.278369",
  "metrics": {
    "end_to_end_latency_ms": 9500,
    "vlm_inference_ms": 9200,
    "agent_reconciliation_ms": 45,
    "within_operational_window": true,
    "cpu_utilization": 25.5,
    "gpu_utilization": 98.0,
    "memory_utilization": 78.2,
    "gpu_memory_utilization": 0.0
  }
}

Status Codes

Code	Description
200	Validation successful
400	Invalid request (missing image or order)
422	Validation error (invalid order format)
500	Server error (VLM or semantic service failure)

Get Validation Result#

Retrieve a validation result by ID.

GET /api/validate/{validation_id}

Parameters

Parameter	Type	Description
`validation_id`	string (path)	UUID of the validation

Example

curl "http://localhost:8083/api/validate/26eba3f8-276b-44ac-b553-74419f84c1ad"

Response

Same schema as POST /api/validate response.

Status Codes

Code	Description
200	Validation found
404	Validation not found

List Validations#

Get all cached validation results.

GET /api/validate

Example

curl "http://localhost:8083/api/validate"

Response

JSON

[
  {
    "validation_id": "uuid-1",
    "image_id": "ORD-001",
    "order_complete": true,
    "accuracy_score": 1.0,
    ...
  },
  {
    "validation_id": "uuid-2",
    "image_id": "ORD-002",
    "order_complete": false,
    "accuracy_score": 0.5,
    ...
  }
]

Delete Validation#

Remove a validation from cache.

DELETE /api/validate/{validation_id}

Example

curl -X DELETE "http://localhost:8083/api/validate/26eba3f8-276b-44ac-b553-74419f84c1ad"

Response

{
  "message": "Validation 26eba3f8-276b-44ac-b553-74419f84c1ad deleted"
}

Status Codes

Code	Description
200	Deleted successfully
404	Validation not found

Batch Validation#

Validate multiple images in one request.

POST /api/validate/batch

Request

Parameter	Type	Description
`images`	file[]	Multiple plate images
`orders`	JSON string	Array of order manifests

Example

curl -X POST "http://localhost:8083/api/validate/batch" \
  -F "images=@plate1.jpg" \
  -F "images=@plate2.jpg" \
  -F 'orders=[
    {"order_id": "ORD-001", "items": [{"name": "Burger", "quantity": 1}]},
    {"order_id": "ORD-002", "items": [{"name": "Pizza", "quantity": 1}]}
  ]'

Response

JSON

{
  "batch_id": "batch-uuid",
  "results": [
    { "validation_id": "uuid-1", ... },
    { "validation_id": "uuid-2", ... }
  ],
  "summary": {
    "total": 2,
    "successful": 2,
    "failed": 0,
    "avg_latency_ms": 9800
  }
}

Response Schemas#

ValidationResult#

Field	Type	Description
`validation_id`	string	Unique identifier
`image_id`	string	Order/image identifier
`order_complete`	boolean	True if all items match
`accuracy_score`	float	0.0-1.0 match ratio
`missing_items`	array	Items not detected
`extra_items`	array	Items detected but not ordered
`quantity_mismatches`	array	Quantity discrepancies
`matched_items`	array	Successfully matched items
`timestamp`	string	ISO 8601 timestamp
`metrics`	object	Performance metrics

Metrics#

Field	Type	Description
`end_to_end_latency_ms`	int	Total request time
`vlm_inference_ms`	int	VLM processing time
`agent_reconciliation_ms`	int	Semantic matching time
`within_operational_window`	boolean	Under target latency
`cpu_utilization`	float	CPU usage percentage
`gpu_utilization`	float	GPU usage percentage
`memory_utilization`	float	Memory usage percentage

Error Responses#

400 Bad Request#

{
  "detail": "Missing required field: image"
}

404 Not Found#

{
  "detail": "Validation with id '...' not found"
}

422 Validation Error#

{
  "detail": [
    {
      "loc": ["body", "order", "items"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

500 Internal Server Error#

{
  "detail": "Validation failed: Circuit breaker is OPEN for OVMS service"
}

Agent Interface (MCP)#

Everything above is the REST API — request/response endpoints called directly by clients (Gradio UI, curl, automated tests). Order Accuracy also exposes a separate MCP server for agents, at http://localhost:8011/mcp.

This is intentionally not a REST endpoint: MCP tools are discovered and invoked over the Model Context Protocol (streamable-http transport), not GET/POST with a fixed URL per resource. An agent connects once and can call any of:

Tool	Equivalent REST concept
`get_order_history`	Read-only query over past `order_validated`/`order_failed` events (no REST equivalent — not stored per-validation-id like `GET /api/validate/{id}`)
`get_station_totals`	Aggregated pass/fail counts per station
`get_rework_rate`	Rework rate for a period, vs. a baseline period
`describe`	Self-description of event types, schemas and tools (SDK built-in)

There are no action tools — Order Accuracy only reports what it sees; it never accepts commands to change orders or system state via MCP.

See the Dine-In README for the full event schema and a runnable fastmcp client example.

Interactive Documentation#

Swagger UI: http://localhost:8083/docs
ReDoc: http://localhost:8083/redoc
OpenAPI JSON: http://localhost:8083/openapi.json