API Reference

All dashboard API endpoints require authentication via a Clerk JWT or API key Bearer token.

Authentication

All API requests must include an Authorization header with either:

• A Clerk JWT: Authorization: Bearer <clerk_jwt> (used by the web dashboard)
• An API key: Authorization: Bearer lh_<your_api_key> (for programmatic access)

API keys can be created in the dashboard under Settings > API Keys. Keys support three scopes: read-only, read-write, and admin.

Traps

GET /dashboard/api/traps

List all traps for the authenticated organization.

{
  "success": true,
  "data": [
    {
      "id": "trap-uuid",
      "name": "robots.txt Trap",
      "path": "/robots.txt",
      "type": "page",
      "description": "Honeypot robots.txt",
      "active": 1,
      "created_at": "2026-03-20T10:00:00.000Z",
      "org_id": "org-uuid"
    }
  ]
}

POST /dashboard/api/traps

Create a new trap.

{
  "name": "API Config Trap",
  "path": "/api/v2/config",
  "type": "api",
  "description": "Honeypot API endpoint"
}

{
  "success": true,
  "data": {
    "id": "new-trap-uuid",
    "name": "API Config Trap",
    "path": "/api/v2/config",
    "type": "api"
  }
}

PATCH /dashboard/api/traps/:id

Update a trap's configuration (name, description, active status).

DELETE /dashboard/api/traps/:id

Delete a trap. This does not delete associated session data.

Sessions

GET /dashboard/api/sessions

List sessions (detected visitors) for the authenticated organization. Supports pagination.

{
  "success": true,
  "data": [
    {
      "id": "session-uuid",
      "source_ip": "203.0.113.42",
      "user_agent": "Mozilla/5.0 ...",
      "classification": "AI_AGENT_MALICIOUS",
      "score": 78,
      "confidence": 92,
      "severity": "critical",
      "signals_fired": ["CALLBACK_HIT", "INJECTION_FOLLOWED", "SYSTEM_PROMPT_LEAKED"],
      "first_seen": "2026-03-20T10:15:00.000Z",
      "last_seen": "2026-03-20T10:15:32.000Z",
      "hit_count": 5
    }
  ]
}

GET /dashboard/api/sessions/:id

Get detailed information for a single session, including all hits, extracted data, and callback payloads.

Analytics

GET /dashboard/api/analytics/overview

Get overview statistics for the dashboard.

{
  "success": true,
  "data": {
    "totalHits24h": 142,
    "agentsDetected": 23,
    "tripwiresFired": 67,
    "promptsCaptured": 8,
    "activeTraps": 12
  }
}

GET /dashboard/api/analytics/severity

Get session counts grouped by severity level.

{
  "success": true,
  "data": {
    "critical": 3,
    "high": 7,
    "medium": 15,
    "low": 42
  }
}

GET /dashboard/api/analytics/timeline

Get hourly hit counts for the past 24 hours, suitable for charting.

Events API

The Events API provides cursor-based pagination over all detection events. This is the recommended API for building custom integrations and dashboard panels.

GET /api/v1/events

List events with cursor-based pagination and optional filters.

{
  "events": [
    {
      "id": "evt_abc123",
      "type": "threat.detected",
      "api_version": "2024-01-01",
      "created_at": "2026-03-20T10:15:00Z",
      "data": {
        "session_id": "ses_xyz",
        "source_ip": "203.0.113.42",
        "classification": "ai_agent",
        "severity": "high",
        "score": 85,
        "hit_count": 3,
        "tripwires_fired": 2,
        "extracted_model": "gpt-4",
        "extracted_operator": "SomeCompany",
        "traps_triggered": ["trap_a", "trap_b"]
      }
    }
  ],
  "has_more": true,
  "next_cursor": "evt_abc122"
}

To paginate, pass cursor=evt_abc122 (the next_cursor value) in your next request. When has_more is false, you've reached the end.

GET /api/v1/events/stream

Server-Sent Events (SSE) endpoint for real-time event streaming. Each message is a JSON event with the same shape as the list endpoint.

Error Responses

All error responses follow a consistent format:

{
  "success": false,
  "error": "Description of what went wrong"
}

Common HTTP status codes:

• 400 -- Bad request (missing or invalid parameters)
• 401 -- Unauthorized (invalid or expired token)
• 403 -- Forbidden (insufficient API key scope)
• 404 -- Resource not found
• 500 -- Internal server error