Skip to main content
Use SimpleKPI through Corsair: one client, typed API calls. Create an API key in SimpleKPI under Settings, then API Access. It starts with skpi_, is shown only once, and is sent as Authorization: Bearer skpi_.... Pass it as the plugin’s key option or store it on the account. Each key carries scopes, and a scope decides which operations work. kpis:read and kpis:write cover KPIs, categories, units, frequencies and icons; entries:read and entries:write cover entries and reports; breakdownitems:read and breakdownitems:write cover breakdowns; users:read covers users. Write does not imply read, so a key that can push entries still cannot list them back. Things to know before you write:
  • PUT replaces the whole object. Anything left out is reset to its default rather than kept, so a rename has to send the rest of the KPI back too. kpis.update documents the full body for that reason.
  • A KPI needs real icon and unit ids. The contract does not mark icon_id and unit_id mandatory, but the API validates whatever arrives, and a missing one becomes 0, which fails with a 400. Read the ids from kpiIcons.list and kpiUnits.list first.
  • Enums are case sensitive. aggregate_function is SUM or AVG, value_direction is U, D or N, and a frequency_id is D, W, M, Q or Y. Lower case is rejected.
  • Entries are upserts. kpi_id, source_id and entry_date identify an entry, so sending the same trio again updates it rather than duplicating. 201 means a new entry and 200 an updated one.
  • A write can store nothing. A valid entry whose actual, target and notes are all empty answers 200 with { stored: false } instead of an entry. The output models both shapes, and the stored flag says which one arrived.
  • The set flags choose what is written. setActual: false leaves a stored actual untouched while a target is written, which is the only way to change a target without clearing the value. addToActual: true adds instead of replacing, which is how you feed in events as they happen.
  • A batch answers 200 even when every row failed. rows_rejected is the only signal. A batch that stored nothing throws, so a caller cannot mistake it for success.
  • Dates have to suit the frequency. A weekly KPI rejects a mid-week entry_date, and the API reports that as a rejected row rather than a failed request.
  • Paging. Lists are plain arrays with no total count. page counts from 1 and rows defaults to 500, so page until a response comes back short.
  • The live API sends a trace id. Errors are RFC 7807 problem details with application/problem+json; a 400 caused by the request carries an errors map from field name to messages, which the plugin surfaces as fieldErrors.
What you get:
  • 38 typed API operations

Setup

1

Install

2

Add the plugin

corsair.ts
With multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.
3

Choose authentication

4

Connect a tenant

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.

Example API calls

Read actuals and targets for one KPI
Record a weekly actual
See the full list on the API page.

What’s next

API reference

Every simplekpi.api.* operation with input and output types.

Connect / OAuth

createLink, Hub delivery, and tenant connect flows.

Use with agents

Expose this plugin’s operations as MCP tools.