API Reference

The APM blueprint exposes REST APIs through two services that are accessible via the NGINX reverse proxy at http://localhost:8080.

Storage Service

The storage service manages detection data written by the agent service and queried by the agent pipeline.

Base URL: http://localhost:8080/api/storage/

Method	Path	Description
POST	/detections	Insert a single detection record
POST	/detections/batch	Bulk insert multiple detections
POST	/detections/query	Run a validated structured query (list, count, aggregate, group-by, or frame summary)
GET	/detections	Query detections — supports label, min_confidence, and limit filters
GET	/detections/summary	Per-class detection statistics
DELETE	/detections	Clear all stored detections
GET	/health	Health check endpoint
GET	/metrics	Prometheus metrics

Example: Insert a Detection

curl -X POST http://localhost:8080/api/storage/detections \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Rupture",
    "confidence": 0.87,
    "bbox": [120, 45, 300, 200],
    "frame_id": 42,
    "timestamp": "2026-06-25T10:00:00Z"
  }'

Example: Query Detections by Label

curl "http://localhost:8080/api/storage/detections?label=Rupture&min_confidence=0.7&limit=20"

Example: Structured Detection Query

POST /detections/query accepts an allowlisted JSON plan, never raw SQL. The operation is one of list, count, aggregate, group_by, or frames. Detection fields are id, frame_id, label, confidence, x, y, width, height, and timestamp. Filters use eq, ne, gt, gte, lt, lte, in, not_in, between, contains, or starts_with. Limits are capped at 500 rows.

curl -X POST http://localhost:8080/api/storage/detections/query \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "group_by",
    "filters": [{"field": "confidence", "operator": "gte", "value": 0.7}],
    "group_by": ["label"],
    "metrics": [
      {"function": "count", "alias": "detections"},
      {"function": "avg", "field": "confidence", "alias": "avg_confidence"}
    ],
    "sort": [{"field": "detections", "direction": "desc"}],
    "limit": 20
  }'

All operations return a stable envelope:

{
  "data": [{"label": "Rupture", "detections": 30, "avg_confidence": 0.84}],
  "meta": {
    "operation": "group_by",
    "returned": 1,
    "fields": ["label", "detections", "avg_confidence"],
    "limit": 20,
    "offset": 0,
    "has_more": false,
    "grouped_by": ["label"]
  }
}

Example: Get Detection Summary

curl http://localhost:8080/api/storage/detections/summary

Sample response:

{
  "total": 120,
  "by_class": {
    "Rupture": 30,
    "Deformation": 55,
    "Disconnect": 10,
    "Obstacle": 25
  },
  "avg_confidence": 0.74
}

Agent Service

The agent service triggers the multi-agent LangGraph pipeline and tracks run results.

Base URL: http://localhost:8080/api/agents/

Method	Path	Description
POST	/runs	Trigger a new agent pipeline run (asynchronous)
GET	/runs	List all agent runs
GET	/runs/{run_id}	Get the status and result of a specific run
GET	/health	Health check endpoint
GET	/metrics	Prometheus metrics

Example: Trigger an Agent Run

curl -X POST http://localhost:8080/api/agents/runs \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "run_id": "abc123",
  "status": "started"
}

Example: Check Run Status

curl http://localhost:8080/api/agents/runs/abc123

When the run completes, the response includes the full ticket generated by the Ticketing Agent:

{
  "run_id": "abc123",
  "status": "completed",
  "ticket": {
    "priority": "HIGH",
    "title": "Rupture detected in pipeline segment A3",
    "description": "Multiple high-confidence Rupture detections observed over 30 frames.",
    "affected_component": "segment-A3",
    "recommended_action": "HALT_PIPELINE",
    "estimated_resolution_time": "4 hours",
    "tags": ["Rupture", "Disconnect"]
  }
}

Prometheus Metrics

Service metrics remain behind the NGINX reverse proxy:

• Storage service: http://localhost:8080/api/storage/metrics — exposes apm_storage_detections_total

• Agent service: http://localhost:8080/api/agents/metrics — exposes apm_agent_runs_total and apm_agent_runs_completed

• Live metrics stream: http://localhost:8080/api/metrics/stream

The optional Prometheus container and the metrics-manager service do not publish host ports. Check their container logs and health status with Docker when diagnosing them.