HTTP API

The REST API is available at http://127.0.0.1:3000/api/v1/ when the proxy is running.

Flows

GET /api/v1/flows

Search and paginate captured flows.

Query Parameters:

• limit — Number of flows to return (default: 50)
• offset — Pagination offset
• filter — Filter expression (e.g., method:GET host:*.example.com)

{
  "flows": [
    {
      "id": "fld_01HX5K9P3Q8Y2Z7",
      "timestamp": "2024-01-15T10:23:45.123Z",
      "method": "GET",
      "url": "https://api.example.com/users",
      "host": "api.example.com",
      "path": "/users",
      "status": 200,
      "duration_ms": 42,
      "size": 1847
    }
  ],
  "pagination": {
    "total": 12847,
    "returned": 10,
    "offset": 0
  }
}

GET /api/v1/flows/:id

Get detailed flow information including headers and body.

Rules

GET /api/v1/rules

List all interception rules.

PUT /api/v1/rules

Create or update a rule.

{
  "id": "rul_01HX5K9P3Q8Y2Z7",
  "name": "Log API requests",
  "priority": 100,
  "filter": {
    "method": "GET",
    "host": "*.example.com",
    "path": "/api/*"
  },
  "action": {
    "type": "log"
  },
  "enabled": true
}

DELETE /api/v1/rules/:id

Delete a rule.

Intercepts

POST /api/v1/intercepts

Create an interception breakpoint.

{
  "filter": {
    "method": "POST",
    "host": "api.example.com"
  },
  "pause_at": "request"
}

POST /api/v1/intercepts/resolve

Resolve a pending intercept (resume, modify, or drop).

{
  "flow_id": "fld_01HX5K9P3Q8Y2Z7",
  "action": "resume",
  "modifications": {}
}

Events

GET /api/v1/events

Server-Sent Events stream for real-time updates.

Event types: flow::new, flow::update, intercept::pending, rule::matched

Metrics

GET /api/v1/metrics

JSON metrics snapshot.

GET /api/v1/metrics/prometheus

Prometheus text format metrics.

# HELP relay_core_flows_total Total number of flows captured
# TYPE relay_core_flows_total counter
relay_core_flows_total 12847

# HELP relay_core_request_duration_ms Request duration in milliseconds
# TYPE relay_core_request_duration_ms histogram
relay_core_request_duration_ms_bucket{le="1"} 10023
relay_core_request_duration_ms_bucket{le="5"} 12500
relay_core_request_duration_ms_bucket{le="10"} 12800
relay_core_request_duration_ms_bucket{le="+Inf"} 12847

Audit

GET /api/v1/audit

Query control-plane mutation audit log.