# 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

```bash
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

```bash
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.

```bash
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:

```json
{
  "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

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

Sample response:

```json
{
  "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

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

Response:

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

### Example: Check Run Status

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

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

```json
{
  "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.