API Reference

Complete documentation for the Edge Funnel Guard REST API. All endpoints accept and return JSON.

Base URL https://edge-funnel-guard.dlh166122.workers.dev

Authentication

All /api/* endpoints require a valid API key. Pass it in the Authorization header using the Bearer scheme. The /health endpoint does not require authentication.

Header Format

HTTP Header 
Authorization: Bearer YOUR_API_KEY

Example Authenticated Request

curl 
curl https://edge-funnel-guard.dlh166122.workers.dev/api/dashboard/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Response (401 Unauthorized)

JSON 
{
  "error": "Unauthorized",
  "message": "Valid API key required. Pass via Authorization: Bearer <key>"
}

Ingestion

POST /api/ingest/event

Ingest a funnel event

Record a single event in the funnel trace. Each event represents one hop (linklet, formdrop, or hookbin). The system automatically calculates the overall trace status based on the combination of hops received.

Request Body

Parameter Type Required Description
trace_id string required Unique identifier for this funnel trace. Ties all three hops together.
hop string required Which step in the funnel. One of: linklet, formdrop, hookbin.
status string required Status of this hop. One of: received, processed, failed.
payload object optional Arbitrary JSON payload for this event (form data, metadata, etc.).
funnel_id string optional Group traces into named funnels (e.g., "summer-campaign", "onboarding-v2").

Example Request

curl 
curl -X POST https://edge-funnel-guard.dlh166122.workers.dev/api/ingest/event \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "t_abc123",
    "hop": "linklet",
    "status": "received",
    "funnel_id": "summer-campaign"
  }'

Response (200 OK)

JSON 
{
  "ok": true,
  "trace_id": "t_abc123",
  "hop": "linklet",
  "event_status": "received",
  "trace_status": "partial"
}

Trace Status Values

Status Meaning
partial Not all three hops have reported yet.
complete All three hops reported with no failures.
failed At least one hop reported failed status.

Dashboard

GET /api/dashboard/traces

List traces

Retrieve a paginated list of traces. Filter by status to find partial or failed funnels quickly.

Query Parameters

Parameter Type Required Description
status string optional Filter by trace status: partial, complete, failed.
limit integer optional Max number of traces to return. Default: 50, max: 200.

Example Request

curl 
curl https://edge-funnel-guard.dlh166122.workers.dev/api/dashboard/traces?status=failed&limit=10 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

JSON 
{
  "traces": [
    {
      "trace_id": "t_abc123",
      "status": "failed",
      "funnel_id": "summer-campaign",
      "hops": {
        "linklet": "received",
        "formdrop": "processed",
        "hookbin": "failed"
      },
      "created_at": "2026-02-20T10:30:00Z",
      "updated_at": "2026-02-20T10:31:15Z"
    }
  ],
  "count": 1
}
GET /api/dashboard/traces/:trace_id

Get trace detail

Retrieve the full detail of a single trace including all events across every hop.

Path Parameters

Parameter Type Description
trace_id string The trace identifier to look up.

Example Request

curl 
curl https://edge-funnel-guard.dlh166122.workers.dev/api/dashboard/traces/t_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

JSON 
{
  "trace_id": "t_abc123",
  "status": "complete",
  "funnel_id": "summer-campaign",
  "hops": {
    "linklet": "received",
    "formdrop": "processed",
    "hookbin": "processed"
  },
  "events": [
    {
      "hop": "linklet",
      "status": "received",
      "payload": null,
      "timestamp": "2026-02-20T10:30:00Z"
    },
    {
      "hop": "formdrop",
      "status": "processed",
      "payload": { "email": "user@example.com" },
      "timestamp": "2026-02-20T10:30:45Z"
    },
    {
      "hop": "hookbin",
      "status": "processed",
      "payload": null,
      "timestamp": "2026-02-20T10:31:02Z"
    }
  ],
  "created_at": "2026-02-20T10:30:00Z",
  "updated_at": "2026-02-20T10:31:02Z"
}
GET /api/dashboard/stats

Get funnel stats

Retrieve aggregate statistics: total traces, completion rate, failure rate, and per-hop breakdowns.

Example Request

curl 
curl https://edge-funnel-guard.dlh166122.workers.dev/api/dashboard/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

JSON 
{
  "total_traces": 1248,
  "complete": 1050,
  "partial": 142,
  "failed": 56,
  "completion_rate": 0.841,
  "failure_rate": 0.045,
  "by_hop": {
    "linklet":  { "received": 1248, "processed": 0, "failed": 0 },
    "formdrop": { "received": 80, "processed": 1112, "failed": 14 },
    "hookbin":  { "received": 12, "processed": 1038, "failed": 42 }
  }
}

Alerts

GET /api/alerts/rules

List alert rules

Retrieve all configured alert rules. Each rule defines a condition that triggers an alert (e.g., failure threshold exceeded).

Example Request

curl 
curl https://edge-funnel-guard.dlh166122.workers.dev/api/alerts/rules \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

JSON 
{
  "rules": [
    {
      "id": "rule_001",
      "name": "High Hookbin Failure Rate",
      "condition": "hop == 'hookbin' AND status == 'failed'",
      "threshold": 5,
      "window_minutes": 10,
      "enabled": true,
      "created_at": "2026-02-19T08:00:00Z"
    }
  ]
}
POST /api/alerts/rules

Create an alert rule

Create a new alert rule. When the number of matching events exceeds the threshold within the time window, an alert is triggered.

Request Body

Parameter Type Required Description
name string required Human-readable name for the rule.
condition string required Matching expression. Supported fields: hop, status, funnel_id.
threshold integer required Number of matching events to trigger the alert.
window_minutes integer required Rolling time window in minutes.
enabled boolean optional Whether the rule is active. Default: true.

Example Request

curl 
curl -X POST https://edge-funnel-guard.dlh166122.workers.dev/api/alerts/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FormDrop Failures",
    "condition": "hop == '\''formdrop'\'' AND status == '\''failed'\''",
    "threshold": 3,
    "window_minutes": 5
  }'

Response (201 Created)

JSON 
{
  "ok": true,
  "rule": {
    "id": "rule_002",
    "name": "FormDrop Failures",
    "condition": "hop == 'formdrop' AND status == 'failed'",
    "threshold": 3,
    "window_minutes": 5,
    "enabled": true,
    "created_at": "2026-02-20T14:00:00Z"
  }
}
GET /api/alerts

List triggered alerts

Retrieve a list of alerts that have been triggered. Each alert references the rule that fired and the events that matched.

Example Request

curl 
curl https://edge-funnel-guard.dlh166122.workers.dev/api/alerts \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

JSON 
{
  "alerts": [
    {
      "id": "alert_0042",
      "rule_id": "rule_001",
      "rule_name": "High Hookbin Failure Rate",
      "triggered_at": "2026-02-20T11:15:00Z",
      "matching_events": 7,
      "window_minutes": 10,
      "sample_trace_ids": [
        "t_x9f2k1",
        "t_m3p7q8",
        "t_r1v4n6"
      ]
    }
  ]
}

System

GET /health

Health check

Returns the service health status. Use this for uptime monitoring.

Example Request

curl 
curl https://edge-funnel-guard.dlh166122.workers.dev/health

Response (200 OK)

JSON 
{
  "status": "ok",
  "timestamp": "2026-02-20T14:30:00Z",
  "version": "1.0.0"
}