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.updatedocuments the full body for that reason. - A KPI needs real icon and unit ids. The contract does not mark
icon_idandunit_idmandatory, but the API validates whatever arrives, and a missing one becomes 0, which fails with a 400. Read the ids fromkpiIcons.listandkpiUnits.listfirst. - Enums are case sensitive.
aggregate_functionisSUMorAVG,value_directionisU,DorN, and afrequency_idisD,W,M,QorY. Lower case is rejected. - Entries are upserts.
kpi_id,source_idandentry_dateidentify an entry, so sending the same trio again updates it rather than duplicating.201means a new entry and200an updated one. - A write can store nothing. A valid entry whose actual, target and notes are all empty answers
200with{ 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: falseleaves a stored actual untouched while a target is written, which is the only way to change a target without clearing the value.addToActual: trueadds instead of replacing, which is how you feed in events as they happen. - A batch answers 200 even when every row failed.
rows_rejectedis 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.
pagecounts from 1 androwsdefaults 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 anerrorsmap from field name to messages, which the plugin surfaces asfieldErrors.
- 38 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the SimpleKPI API key before the first call: More: API Key
pnpm corsair setup --plugin=simplekpi --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.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 KPIWhat’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.