REST API

Claw Insights provides REST endpoints for health checks and snapshot generation.

AI Agents

If you're building an AI agent integration, consider using the snapshot skill for automatic discovery — or use the REST endpoints below for direct programmatic access.

GET /health

Health check endpoint. No authentication required.

curl http://127.0.0.1:41041/health

Returns 200 OK with server status.

POST /api/snapshot

Generate a dashboard snapshot image or data export.

Authentication

Requires a valid Bearer token (Authorization: Bearer <token>) unless running in no-auth mode.

Security: No-Auth Mode

When noAuth is enabled, the snapshot endpoint is protected by localOnlyMiddleware — only requests from 127.0.0.1 / ::1 (localhost) are accepted. Remote requests receive 403 Forbidden. This prevents unauthenticated access from the network.

Parameters

Parameter	Type	Default	Values	Description
detail	string	standard	compact, standard, full	Detail level
format	string	png	png, svg, json	Output format
range	string	24h	30m, 1h, 6h, 12h, 24h	Time range
theme	string	dark	dark, light	Color theme
lang	string	en	en, zh	Language

Note: The REST API defaults range to 24h. The CLI snapshot command defaults to 6h.

Example

curl -X POST http://127.0.0.1:41041/api/snapshot \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"format": "png", "detail": "full", "range": "24h", "theme": "dark"}' \
  -o snapshot.png

Response Headers

Header	Description
Content-Type	MIME type of the response (image/png, image/svg+xml, application/json)
Content-Disposition	Suggested filename with timestamp and parameters
X-Snapshot-Duration	Render time in milliseconds
X-Snapshot-Degraded-Sources	Comma-separated list of data sources that failed gracefully
X-Snapshot-Degraded	Present when detail level was auto-downgraded to fit the 2MB size limit

Error Codes

Code	HTTP Status	Description
INVALID_PARAM	400	Invalid or unsupported parameter value
RATE_LIMITED	429	Too many snapshot requests — try again later
QUEUE_FULL	503	Render queue is full
QUEUE_TIMEOUT	503	Queue wait timed out
COLLECT_TIMEOUT	504	Data collection timed out for one or more sources
TOTAL_TIMEOUT	504	Total snapshot timeout exceeded
PAYLOAD_TOO_LARGE	413	Snapshot exceeds 2MB at all detail levels
GATEWAY_UNREACHABLE	502	OpenClaw Gateway is not reachable
RENDER_FAILED	500	Snapshot rendering failed