BackAPI reference

Breakdown Items

A breakdown splits one KPI so it reports separately for each of its parts — a person, a team, a product, a region. Each part is a breakdown item, and writing an entry against one is what produces a per-part figure rather than a single account-wide number.

An item usually belongs to a single breakdown — "North" under "Region" — and names it in breakdown_id. An item that combines several breakdowns leaves that null.

A KPI entry refers to an item as source_id, not breakdown_item_id. That field name predates the rename and was kept so existing integrations keep working. Pass the id from this resource into it — see KPI Entries.

This resource used to live at /v1/sources. That path still answers, with 410 Gone and a message naming its replacement, so an integration written against it fails loudly rather than silently reading an empty list. Update the path; the request and response shapes are unchanged.

The scopes moved with it. Keys that held sources:read or sources:write were migrated to the breakdown item scopes automatically, so nothing needs reissuing.

The Classic API has no equivalent — it used groups and group items instead. See Moving from Classic.

Base URL https://api.simplekpi.com/v1

Endpoints

List breakdown items — GET /v1/breakdownitems
Create a breakdown item — POST /v1/breakdownitems
Get a breakdown item — GET /v1/breakdownitems/{id}
Update a breakdown item — PUT /v1/breakdownitems/{id}
Delete a breakdown item — DELETE /v1/breakdownitems/{id}

Breakdown item object

Name	Type	Read Only	Mandatory	Max Len.	Notes
`id`	integer	yes	no		Assigned by SimpleKPI when the item is created. Send this value as source_id when writing a KPI entry against the item.
`name`	string	no	yes	100	What this part of the breakdown is called, e.g. a person, team, product or region.
`breakdown_id`	integer	no	no		Nullable. Which breakdown the item sits under. Null when the item combines more than one breakdown rather than belonging to a single one.
`user_id`	integer	yes	no		Nullable. For an item under the People breakdown, the person it stands for. Null for every other kind, and not settable here.
`is_system`	boolean	no	no		True for items SimpleKPI maintains itself. Leave it false when creating one; it is ignored on update, because a built-in item cannot be made ordinary through the API.
`is_archived`	boolean	no	no		Archived items keep their history but stop being offered for new entries.
`sort_order`	integer (16 bit)	no	no		Position of the item within its breakdown.
`created_at`	datetime	yes	no
`updated_at`	datetime	yes	no

List breakdown items

GET /v1/breakdownitems

Returns both ordinary items and the sets that combine several breakdowns. A set has a null breakdown_id.

Requires breakdownitems:read on the API key.

Parameters

Name	Type	Required	Default	Notes
`page`	integer	no	1	Which page to return, counting from 1.
`rows`	integer	no	500	How many rows per page. Defaults to 500.

Using curl

curl https://api.simplekpi.com/v1/breakdownitems \
  -H "Authorization: Bearer skpi_your_api_key"

Example response

Status: 200 OK
[
  {
    "id": 77,
    "name": "North",
    "breakdown_id": 12,
    "user_id": null,
    "is_system": false,
    "is_archived": false,
    "sort_order": 1,
    "created_at": "2026-02-21T10:57:00",
    "updated_at": "2026-02-21T10:57:00"
  }
]

Status codes

Code	Meaning
`200`	OK
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`429`	Too Many Requests

Create a breakdown item

POST /v1/breakdownitems

The breakdown itself is created in the app; this adds an item to one that already exists.

Requires breakdownitems:write on the API key.

Using curl

curl https://api.simplekpi.com/v1/breakdownitems \
  -X POST \
  -H "Authorization: Bearer skpi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"North","breakdown_id":12,"is_system":false,"is_archived":false,"sort_order":1}'

Example request body

{
  "name": "North",
  "breakdown_id": 12,
  "is_system": false,
  "is_archived": false,
  "sort_order": 1
}

Status codes

Code	Meaning
`201`	Created
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`409`	Conflict
`429`	Too Many Requests

Get a breakdown item

GET /v1/breakdownitems/{id}

Requires breakdownitems:read on the API key.

Parameters

Name	Type	Required	Default	Notes
`id`	integer	yes		The breakdown item to return.

Using curl

curl https://api.simplekpi.com/v1/breakdownitems/{id} \
  -H "Authorization: Bearer skpi_your_api_key"

Status codes

Code	Meaning
`200`	OK
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found
`429`	Too Many Requests

Update a breakdown item

PUT /v1/breakdownitems/{id}

A full replacement, not a patch.

Requires breakdownitems:write on the API key.

Parameters

Name	Type	Required	Default	Notes
`id`	integer	yes		The breakdown item to replace.

Using curl

curl https://api.simplekpi.com/v1/breakdownitems/{id} \
  -X PUT \
  -H "Authorization: Bearer skpi_your_api_key"

Status codes

Code	Meaning
`200`	OK
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found
`409`	Conflict
`429`	Too Many Requests

Delete a breakdown item

DELETE /v1/breakdownitems/{id}

Archive an item you still want history for — deleting removes it outright.

Requires breakdownitems:write on the API key.

Parameters

Name	Type	Required	Default	Notes
`id`	integer	yes		The breakdown item to delete.

Using curl

curl https://api.simplekpi.com/v1/breakdownitems/{id} \
  -X DELETE \
  -H "Authorization: Bearer skpi_your_api_key"

Status codes

Code	Meaning
`204`	No Content
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found
`429`	Too Many Requests

Breakdown Items

Endpoints

Breakdown item object

List breakdown items

Parameters

Using curl

Example response

Status codes

Create a breakdown item

Using curl

Example request body

Status codes

Get a breakdown item

Parameters

Using curl

Status codes

Update a breakdown item

Parameters

Using curl

Status codes

Delete a breakdown item

Parameters

Using curl

Status codes

We value your privacy