Observability Event Schema

This page is the data reference for what Lander reports to the control plane: the observability event, and the device registration and inventory payloads. For how these are produced and consumed, see Observability events. For the HTTP endpoints, see the API Reference.

Observability event

One event describes one MCP tool call. Events are sent in batches to POST /v1/devices/events and stored for the event browser and summary.

Field	Type	Description
event_time	timestamp	When the call occurred (endpoint clock)
agent_type	string	Calling agent, e.g. claude-code, gemini-cli
mcp_name	string	MCP server invoked
tool	string	Tool called on that server
event_type	string	Kind of event (invocation, result, error)
result	enum	allowed, denied, or error
deny_code	string	Machine code for a deny (when result = denied)
deny_reason	string	Human-readable deny explanation
error_message	string	Error detail (when result = error)
rule_applied	string	The rule/policy that produced a deny
model	string	Model driving the agent, when known
session_id	string	Groups calls within one agent session
group	string	Organizational grouping
actor_email	string	Human owner of the device/agent
tokens_in	integer	Input tokens attributed to the call
tokens_out	integer	Output tokens attributed to the call
duration_ms	integer	Call duration in milliseconds
skills	string[]	Skill names involved
prompt	string	Request prompt, optionally truncated
metadata	object	Arbitrary additional fields

On the server, each stored event is also stamped with received_at (server clock), the verified device_id / serial_number, and the source IP.

Example event

{
  "event_time": "2026-06-22T15:04:05Z",
  "agent_type": "claude-code",
  "mcp_name": "github",
  "tool": "list_issues",
  "event_type": "result",
  "result": "allowed",
  "model": "claude-opus-4-8",
  "session_id": "s_8f2c…",
  "actor_email": "dev@example.com",
  "tokens_in": 1820,
  "tokens_out": 340,
  "duration_ms": 412,
  "skills": [],
  "prompt": "list open issues in the repo",
  "metadata": {}
}

Example denied event

{
  "event_time": "2026-06-22T15:06:10Z",
  "agent_type": "claude-code",
  "mcp_name": "github",
  "tool": "delete_repo",
  "event_type": "invocation",
  "result": "denied",
  "deny_code": "TOOL_DISABLED",
  "deny_reason": "Tool 'delete_repo' is disabled by policy",
  "rule_applied": "disabled-tools",
  "actor_email": "dev@example.com",
  "duration_ms": 2
}

Device registration payload

Sent to POST /v1/devices/register, signed with the device key and carrying the authenticated user’s bearer token — this endpoint is the one device route that requires user authentication (see Authenticated enrollment).

Field	Type	Description
serialNumber	string	Hardware serial or persisted fallback UUID
brand	string	Apple (hardware) or lander (fallback)
model	string	Hardware model or hostname
certificate	string (PEM)	Self-signed device certificate
ownerEmail	string	Ignored for ownership. Accepted for wire compatibility and kept in the canonical signed payload, but never resolved to a user — the owner is the authenticated caller
clientTimestamp	timestamp (RFC3339)	Signing timestamp
signature	string (base64)	Signature over the canonical payload

Response: deviceId, certificateFingerprint, and ownerAssigned — now always true, since the owner is taken from the token’s subject rather than matched from a claimed address. Without a valid token the request is rejected with 401 and no device is created.

Inventory payload

Sent to POST /v1/devices/inventory (signed via the X-Device-Signature header). Reports agents and their MCPs — names and transports only, never the command/args/env that may carry secrets (see Security & audit).

{
  "certificate": "-----BEGIN CERTIFICATE-----\n…",
  "clientTimestamp": "2026-06-22T15:00:00Z",
  "agents": [
    {
      "agentType": "claude-code",
      "displayName": "Claude Code",
      "mcps": [
        { "name": "github", "enabled": true, "transport": "stdio" },
        { "name": "postgres", "enabled": true, "transport": "http" }
      ]
    }
  ]
}

Response: success, deviceId, agentsIn, mcpsIn, and receivedAt.

MCP entry (in inventory)

Field	Type	Description
name	string	MCP server name
enabled	boolean	Whether it’s enabled for the agent
transport	string	stdio, http, or sse