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:

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

curl -X GET https://lobsterhoney.com/dashboard/api/traps \
  -H "Authorization: Bearer lh_YOUR_API_KEY"

Traps

GET /dashboard/api/traps

List all traps for the authenticated organization.

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

POST /dashboard/api/traps

Create a new trap.

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

# Response
{
  "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.

# Query parameters
# ?limit=20     - Number of results (default 20, max 100)
# ?offset=0     - Pagination offset
# ?classification=AI_AGENT_MALICIOUS  - Filter by classification

# Response
{
  "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.

# Response
{
  "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.

# Response
{
  "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.

Error Responses

All error responses follow a consistent format:

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

Common HTTP status codes: