API Reference

Leadmetrics exposes separate API surfaces per client, all served from a single Fastify instance. Common middleware (auth, rate limiting, error handling, pagination) is shared across all surfaces.

API Surfaces

Doc	Prefix	Client	Audience
Overview	—	All	Architecture, auth, errors, pagination
Gateway	—	All	Cross-cutting concerns — auth, audit, rate-limit, throttle, logging
Auth & Callbacks	`/auth/v1`, `/agent/v1`	All	Login, refresh, OAuth, agent phone-home
Dashboard API	`/dashboard/v1`	`apps/dashboard` (web)	Tenant marketing teams
DM Portal API	`/dm/v1`	`apps/dm-portal`	Internal DM reviewers (cross-tenant)
Admin API	`/admin/v1`	`apps/manage`	Platform super-admins
Mobile API	`/mobile/v1`	`apps/dashboard` (React Native)	Tenant users on mobile
CLI API	`/cli/v1`	`apps/cli` (`lm`)	Internal Leadmetrics / DM team
Agent API	`/agent/v1`	Agent runtimes	LLM callbacks, streaming, health

Quick Reference

Auth flow


POST /auth/v1/login           → access token + refresh token
POST /auth/v1/refresh         → new access token
GET  /auth/v1/me              → current user profile
POST /auth/v1/logout          → revoke refresh token

Core resource paths (Dashboard)


GET  /dashboard/v1/campaigns                    → campaign list
POST /dashboard/v1/campaigns                    → submit campaign brief
GET  /dashboard/v1/approvals                    → approval queue
POST /dashboard/v1/approvals/:id/resolve        → approve / reject
GET  /dashboard/v1/activities/:id/stream        → SSE live output
GET  /dashboard/v1/events/stream                → SSE platform events

Key DM paths


GET  /dm/v1/overview                            → cross-tenant mission control
GET  /dm/v1/approvals                           → cross-tenant approval queue
POST /dm/v1/approvals/bulk/resolve              → bulk approve
POST /dm/v1/activities/:id/pause                → pause running activity

Admin paths


GET  /admin/v1/tenants                          → all tenants
POST /admin/v1/tenants/:id/impersonate          → impersonation token
PATCH /admin/v1/agent-configs/:role             → update master agent config
POST /admin/v1/agent-configs/:role/push         → push config to tenants
GET  /admin/v1/system/health                    → platform health

Mobile extras


POST /mobile/v1/push/devices                    → register push token
GET  /mobile/v1/notifications                   → notification history
GET  /mobile/v1/home                            → single-request home screen aggregate

Agent callbacks & control plane tools


POST /agent/v1/runs/:runId/result                   → deliver result
POST /agent/v1/runs/:runId/stream                   → stream output token-by-token
GET  /agent/v1/runs/:runId/context                  → fetch task context at run start
POST /agent/v1/runs/:runId/actions/create-subtask   → delegate to another agent
POST /agent/v1/runs/:runId/actions/create-approval  → create approval gate
POST /agent/v1/runs/:runId/actions/request-review   → request mid-task human review
POST /agent/v1/runs/:runId/actions/report-blocker   → signal activity blocked
POST /agent/v1/runs/:runId/actions/reassign         → reassign activity
GET  /agent/v1/health/:agentRole                    → adapter health check
GET  /agent/v1/skills/:agentRole                    → skill manifest
GET  /agent/v1/skills/:agentRole/:skillName         → full skill content