Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.esperr.com/llms.txt

Use this file to discover all available pages before exploring further.

​
How It Works

When you use Esper, your traffic data flows through the Beacon Server:
  1. Traffic Collection: Your events are automatically forwarded to the Beacon Server
  2. Authentication: Only traffic with valid API keys is accepted
  3. Processing: Events are validated and prepared for analysis
  4. Policy Evaluation: Events are evaluated against your deployed policies

​
Sending Traffic to Beacon

The easiest way to send traffic is using esper capture: 
# Start automatic traffic forwarding
esper capture run
This command:
  • Monitors your network traffic automatically
  • Forwards relevant events to the Beacon Server
  • Requires zero changes to your applications
  • Continues working even if Esper has issues (fail-safe design)

​
Cloud HTTP

If the customer is using cloud, send the observed request or event to Esper over HTTP and wait for the mitigation context in the response.
AuthenticationCloud ingest uses the x-esper-api-key header. The customer only needs their Esper API key to start sending traffic.
Integration Point RequiredIf the customer is not touching code, they still need some place to attach that header, such as middleware, a reverse proxy, a serverless platform hook, or a prebuilt Esper connector.
Start From A Shipped IntegrationIf you want a guided setup instead of building the request boundary yourself, start with the Integrations section.
curl -X POST https://api.esper.example/api/v1/beacon/event \
  -H "x-esper-api-key: YOUR_ESPER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "tenant_id": "11111111-1111-1111-1111-111111111111",
    "source": "web",
    "observed_at": "2026-03-26T12:00:00Z",
    "idempotency_key": "req-0001",
    "request": {
      "method": "POST",
      "path": "/login",
      "client_ip": "203.0.113.10",
      "user_agent": "Mozilla/5.0"
    },
    "fields": {
      "email": "user@example.com",
      "account_id": "acct-123"
    }
  }'
Minimal response shape: 
{
  "item_id": "8bfc42be-8c1c-4c69-bc92-2d16d1f7d7e8",
  "lookup_entity_id": "1b1d1bb1-5ce1-59fd-bf3e-939e6d8f3d26",
  "active_mitigation": {
    "decision": "Block"
  }
}
For new customers, start with cloud before you introduce Hybrid. It isthe shortest path to a working integration.

​
Direct API Integration

For custom integrations, send the same structured event shape directly to the Beacon ingest API: 
curl -X POST https://api.esper.example/api/v1/beacon/event \
  -H "x-esper-api-key: YOUR_ESPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "11111111-1111-1111-1111-111111111111",
    "source": "api",
    "observed_at": "2026-03-26T12:00:00Z",
    "fields": {
      "action": "login",
      "user": "user@example.com"
    }
  }'

​
Security

  • Encrypted Transport: All traffic uses TLS encryption
  • API Key Authentication: Each request must include your unique API key
  • Rate Limiting: Automatic protection against traffic spikes
  • Data Isolation: Your events are completely isolated from other customers

​
Performance

The Beacon Server is designed to handle high-volume traffic:
  • Automatically scales during traffic spikes
  • Batching support for improved efficiency
  • Geographic distribution for low latency

​
Monitoring

You can monitor your Beacon Server usage in the Esper dashboard:
  • Events received per second
  • Authentication failures
  • Processing latency
  • Error rates

​
Integration guides

Use the recipe-backed docs when you want Esper at an existing traffic boundary: