API endpoints

Base URL https://api.insightos.com. Every response uses the envelope { success, data }.

MethodPathWhat it does
POST/auth/loginAuthenticate and receive a JWT
POST/auth/registerCreate an account and its agency workspace
POST/auth/forgot-passwordRequest a password reset link
POST/auth/reset-passwordConsume a reset token and set a new password
GET/auth/meThe signed-in user’s profile
GET/clientsEvery client this user can reach
POST/clientsAdd a client (metered against the plan)
GET/clients/:idOne client
PATCH/clients/:idUpdate a client
DELETE/clients/:idRemove a client and its data
GET/clients/:id/kpisDaily normalised metrics
GET/clients/:id/kpis/summaryAggregated metrics with a comparison period
GET/clients/:id/integrationsConnections belonging to a client
GET/clients/:id/reportsReports generated for a client
POST/clients/:id/reports/weeklyQueue a weekly PDF (metered monthly)
GET/clients/:id/alertsAlert rules for a client
POST/clients/:id/alertsCreate an alert rule
GET/clients/:id/goalsKPI goals for a client
GET/clients/:id/insightsThe written summary for a period
GET/clients/:id/benchmarksThis client against your portfolio
GET/clients/:id/recommendationsAutomated suggestions
GET/clients/alerts/summaryUnresolved alerts across every client
GET/workspacesWorkspaces this user belongs to
POST/workspacesCreate a workspace (admin only)
GET/workspaces/:id/membersMembers of a workspace (admin only)
GET/api-keysAPI keys issued for this agency
POST/api-keysIssue a key — the secret is returned once
DELETE/api-keys/:idRevoke a key
GET/webhooksWebhook endpoints
POST/webhooksRegister an endpoint — the signing secret is returned once
GET/usageUsage against the plan limits
GET/billing/statusPlan and subscription state
GET/audit-logCompliance audit trail (admin only)
GET/healthLiveness check (public)

Authenticating

Everything except /auth/login, /auth/register, the password-reset routes and /health requires a credential. A JWT identifies a person; an API key identifies the workspace and carries its own scopes.

Authorization: Bearer <jwt>
X-API-Key: <api-key>

Statuses worth handling

402 means a plan limit was reached; the body names the resource, the current usage, the plan and the upgrade target. 403 means the role is not permitted. 429 means you are being rate-limited — back off and retry.


Something missing or wrong here? support@insightos.com