SimpleKPI AI › API reference

Moving from the Classic API

If you have an integration written against theSimpleKPI Classic Developer API, this page covers what changes. The object shapes are largely the same — field names carried over deliberately — so most of the work is authentication, the base URL, and the handful of resources that no longer exist.

Nothing here affects existing Classic accounts. The Classic API is unchanged and its documentation stays where it is; this is only about integrating with SimpleKPI AI.

At a glance

Authentication

Replace the basic-auth credentials with a bearer token.

# Classic
curl https://acme.simplekpi.com/api/kpis -u alex@example.com:0f3c…

# SimpleKPI AI
curl https://api.simplekpi.com/v1/kpis -H "Authorization: Bearer skpi_…"

The email address is gone from the request entirely. In Classic it chose which user a write was attributed to; in SimpleKPI AI the key itself carries that, fixed when the key is created. Create a key from the account you want writes attributed to.

Because keys are scoped, an integration that only pushes entries no longer needs credentials that can also delete users. Grantentries:write and nothing else. SeeAuthentication.

URLs

The host no longer varies by account — every account usesapi.simplekpi.com, and the key identifies the tenant. The path prefix is /v1 rather than /api.

Resource paths themselves are unchanged, so/api/kpientries becomes /v1/kpientries.

Resources that no longer exist

SimpleKPI AI organises breakdowns differently, so three parts of the Classic API have no direct equivalent. These are the ones to plan around.

Groups

There is no /v1/groups. Classic groups were containers of group items used to break a KPI down; SimpleKPI AI models that as abreakdown made up of rows, one per part.

The nearest thing to a group is a breakdown, and breakdowns are created in the app rather than through the API. What the API does expose is their members — see Breakdown Items, where each row carries the breakdown_id it belongs to. Code that created groups on the fly needs the breakdown to exist first; code that only read them can list breakdown rows and group by breakdown_id.

Group items

Neither /api/groups/{id}/items nor/api/users/{id}/groupitems has a successor. A group item is now a breakdown item, and breakdown items are a top-level resource rather than something nested under a group or a user.

So a call that listed one group's items becomesGET /v1/breakdownitems filtered on breakdown_id, and an item that represents a person carries user_id instead of being reached through the user. Breakdown items also support archiving, which group items did not: an archived item keeps its history but stops being offered for new entries.

One naming quirk to watch. The resource is breakdownitems, but a KPI entry still refers to one as source_id rather thanbreakdown_item_id. That field name predates the rename and was kept so existing integrations keep working.

User / KPI assignments

There is no /v1/users/{id}/kpis. In Classic you assigned KPIs to users explicitly; in SimpleKPI AI what a person is measured on follows from the breakdown a KPI uses and the item within it that represents them.

There is no API call that reproduces the old assignment list. To record a value against a particular person, write the entry with theirsource_id — or with user_id, which resolves to the same place. See KPI Entries.

Everything else maps across

Behaviour worth re-testing

• Mandatory fields differ. Do not assume the Classic tables still apply — each field table in this reference is generated from the live contract. Check the ones you send.
• Errors changed shape. Anything parsing Classic error messages needs updating for problem details, and validation failures now name the offending field.
• Rate limits are enforced. A tight loop that was fine against Classic can now earn a 429. Handle Retry-After, and use the batch endpoint for bulk loads.
• XML is gone. Any client asking for application/xml needs to move to JSON.