API Overview
Audience: Integration developers and application administrators
Address and authentication
Use your deployment's configured API base URL. Paths below are relative to it; do not automatically append /api or /api/v1 to the web application address.
Protected user calls require Authorization: Bearer <access_token>, and company-scoped calls also require X-Tenant-ID: <tenant_id>. Users can access only authorized companies and records; supplying a company ID does not grant access. Use Content-Type: application/json when sending JSON.
The authentication guide explains login, refresh cookies, company switching and logout. The Push Measurement API uses a separate x-api-key; a push key does not replace a user JWT.
Common calls
| Method | Path | Operation |
|---|---|---|
| POST | /auth/login | Email/password login, access token and refresh session |
| POST | /auth/session | New access token using the HttpOnly refresh cookie |
| POST | /auth/refresh | Renew using a still-valid access token |
| POST | /auth/logout | End the valid-token and refresh session |
| POST | /auth/session/logout | End the refresh session without an access token |
| GET | /auth/profile | Account and membership context |
| POST | /auth/switch-tenant | Switch to an authorized company |
| GET | /plans/resource-usage | Company resource usage and limits |
| GET | /plans/effective/:groupId | Group's effective entitlements |
| GET | /plans/my-groups | Effective entitlements for the user's groups |
| GET | /kpis | KPI register list |
| POST | /kpis | Create a KPI |
| GET / PATCH / DELETE | /kpis/:id | Read / update / delete a KPI |
| POST | /kpis/:id/retire, /kpis/:id/reactivate | Retire / reactivate |
| GET / POST | /kpis/:id/measurements | List / add measurements |
| PATCH / DELETE | /kpis/:id/measurements/:measurementId | Update / delete a measurement |
| GET | /kpis/:id/usages, /kpis/:id/audit | Report usages / KPI history |
| PUT | /kpis/:id/success-criteria | Save success criteria with version checking |
| GET / POST | /kpi-usages/:parentType/:parentId | List / add report KPI usages |
| PUT | /kpi-usages/:parentType/:parentId/weights | Update report weights |
| PATCH / DELETE | /kpi-usages/:parentType/:parentId/:usageId | Update / remove one usage |
| GET | /reports/performance/units, /reports/performance/persons, /reports/performance/my | Performance reports within your scope |
| GET | /dashboard/admin, /dashboard/unit-leader, /dashboard/member, /dashboard/strategy-compass | Dashboard data with role and record scope applied |
| GET | /ai-assistant/models, /ai-assistant/agents | Available model and agent options |
| GET / POST | /ai-assistant/conversations | List / create your conversations |
| GET / PATCH / DELETE | /ai-assistant/conversations/:id | Read / update / delete your conversation |
| POST | /ai-assistant/agui/:agentId | AG-UI request; response is an SSE event stream rather than JSON |
| POST | /ai-assistant/conversations/:id/cancel | Stop an active conversation run |
Each method applies only to the path where it is listed. Replace placeholders such as :id with actual IDs. This list does not enumerate every sub-operation of every resource.
Locate module paths
Organization uses /org, products /products, planning periods /strategic-cycles, mission/vision /mission-vision, status reports /current-states, analyses /resources-vrio, /pestle, /porter-5, /bcg-matrix, /digital-maturity, /excellence-assessments, /product-scorecard, /findings; SWOT uses /swot, focus areas /strategic-themes, and OKRs /new-okr. These are module prefixes; they do not imply identical GET/POST/PATCH support at every prefix.
In SaaS, the Super Admin reads the catalog with GET /admin/entitlements/catalog, lists groups with GET /admin/entitlements/sets, and reads/saves one set with GET/PUT /admin/entitlements/sets/:groupId. Saving requires the current expectedVersion; a concurrent change returns 409. On-prem installations disable set management and use the signed license and file catalog.
In development/staging, Swagger at /api provides methods, request bodies, query parameters and response schemas; this interface is disabled in production.
Errors and operation safety
- 400: Invalid field/format or business rule; inspect the response explanation.
- 401: Invalid session or token. Restore the session if a valid refresh cookie is available.
- 403: Access denied by role, company/record scope, menu, module or installation license.
- 404: Resource missing or inaccessible in this scope.
- 409: Version/concurrent-change conflict; reload the current data and reassess.
- 422: Business-rule restriction such as a resource limit.
- 429: Endpoint rate limit exceeded. Limits depend on the endpoint and configuration.
Do not blindly retry a write whose result is unknown; handle duplicate-record/measurement risks according to that endpoint's contract. Keep tokens and secret keys out of logs when recording response code and message fields.