> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logfleet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Edge API Overview

> Endpoints used by edge agents

The Edge API is used by LogFleet edge agents running on your distributed devices. These endpoints use **API Key authentication** instead of JWT tokens.

## Authentication

All Edge API requests must include the `X-API-Key` header:

```bash theme={null}
curl -X POST https://api.logfleet.io/api/v1/edge/register \
  -H "X-API-Key: lf_prod_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456" \
  -H "Content-Type: application/json" \
  -d '{"name": "edge-location-01"}'
```

## Agent Lifecycle

```
1. Register    → Agent announces itself to LogFleet
2. Heartbeat   → Periodic health check (every 30s)
3. Metrics     → Push extracted metrics (every 60s)
4. Sync Config → Fetch latest metric configurations
5. Stream      → On-demand log streaming when requested
```

## Endpoints

| Endpoint                              | Purpose                     | Frequency        |
| ------------------------------------- | --------------------------- | ---------------- |
| `POST /edge/register`                 | One-time agent registration | Once at startup  |
| `POST /edge/agents/{id}/heartbeat`    | Health check                | Every 30 seconds |
| `POST /edge/agents/{id}/metrics`      | Push metrics                | Every 60 seconds |
| `GET /edge/agents/{id}/metric-config` | Sync configurations         | Every 60 seconds |
| `POST /edge/agents/{id}/stream`       | Start log streaming         | On-demand        |

## Required Permissions

Create API keys with appropriate permissions for edge agents:

```json theme={null}
{
  "name": "Production Agents",
  "permissions": [
    "edge:register",
    "edge:heartbeat",
    "edge:metrics",
    "edge:stream"
  ]
}
```

| Permission       | Required For         |
| ---------------- | -------------------- |
| `edge:register`  | Initial registration |
| `edge:heartbeat` | Heartbeat signals    |
| `edge:metrics`   | Pushing metrics      |
| `edge:stream`    | Log streaming        |

<Note>
  For security, grant only the permissions each agent needs.
  If an agent only sends heartbeats and metrics, omit `edge:stream`.
</Note>