API endpoints
Base URL https://api.insightos.com. Every response uses the envelope { success, data }.
| Method | Path | What it does |
|---|---|---|
POST | /auth/login | Authenticate and receive a JWT |
POST | /auth/register | Create an account and its agency workspace |
POST | /auth/forgot-password | Request a password reset link |
POST | /auth/reset-password | Consume a reset token and set a new password |
GET | /auth/me | The signed-in user’s profile |
GET | /clients | Every client this user can reach |
POST | /clients | Add a client (metered against the plan) |
GET | /clients/:id | One client |
PATCH | /clients/:id | Update a client |
DELETE | /clients/:id | Remove a client and its data |
GET | /clients/:id/kpis | Daily normalised metrics |
GET | /clients/:id/kpis/summary | Aggregated metrics with a comparison period |
GET | /clients/:id/integrations | Connections belonging to a client |
GET | /clients/:id/reports | Reports generated for a client |
POST | /clients/:id/reports/weekly | Queue a weekly PDF (metered monthly) |
GET | /clients/:id/alerts | Alert rules for a client |
POST | /clients/:id/alerts | Create an alert rule |
GET | /clients/:id/goals | KPI goals for a client |
GET | /clients/:id/insights | The written summary for a period |
GET | /clients/:id/benchmarks | This client against your portfolio |
GET | /clients/:id/recommendations | Automated suggestions |
GET | /clients/alerts/summary | Unresolved alerts across every client |
GET | /workspaces | Workspaces this user belongs to |
POST | /workspaces | Create a workspace (admin only) |
GET | /workspaces/:id/members | Members of a workspace (admin only) |
GET | /api-keys | API keys issued for this agency |
POST | /api-keys | Issue a key — the secret is returned once |
DELETE | /api-keys/:id | Revoke a key |
GET | /webhooks | Webhook endpoints |
POST | /webhooks | Register an endpoint — the signing secret is returned once |
GET | /usage | Usage against the plan limits |
GET | /billing/status | Plan and subscription state |
GET | /audit-log | Compliance audit trail (admin only) |
GET | /health | Liveness 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