BackAPI reference
- Overview
- Authentication
- Errors and limits
- Code examples
- Moving from Classic
- KPIs
- KPI Categories
- KPI Categories / KPIs
- Breakdown Items
- KPI Entries
- KPI Frequencies
- KPI Icons
- KPI Units
- Reports
- Users
SimpleKPI AI › API reference
KPI Categories
Categories group KPIs so they can be found and reported on together. Every KPI belongs to one. A category has to be empty before it can be deleted.
Base URL https://api.simplekpi.com/v1
Endpoints
- List KPI categories —
GET /v1/kpicategories - Create a KPI category —
POST /v1/kpicategories - Get a KPI category —
GET /v1/kpicategories/{id} - Update a KPI category —
PUT /v1/kpicategories/{id} - Delete a KPI category —
DELETE /v1/kpicategories/{id}
KPI category object
| Name | Type | Read Only | Mandatory | Max Len. | Notes |
|---|---|---|---|---|---|
id | integer | yes | no | Assigned by SimpleKPI when the category is created. | |
name | string | no | yes | 50 | What the category is called. |
sort_order | integer (16 bit) | no | no | Position of the category in the list. | |
created_at | datetime | yes | no | ||
updated_at | datetime | yes | no |
List KPI categories
GET /v1/kpicategories
Requires kpis: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/kpicategories \ -H "Authorization: Bearer skpi_your_api_key"
Example response
Status: 200 OK
[
{
"id": 5478,
"name": "Sales",
"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 KPI category
POST /v1/kpicategories
Requires kpis:write on the API key.
Using curl
curl https://api.simplekpi.com/v1/kpicategories \
-X POST \
-H "Authorization: Bearer skpi_your_api_key" \
-H "Content-Type: application/json" \
-d '{"name":"Sales","sort_order":1}'Example request body
{
"name": "Sales",
"sort_order": 1
}Status codes
| Code | Meaning |
|---|---|
201 | Created |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
409 | Conflict |
429 | Too Many Requests |
Get a KPI category
GET /v1/kpicategories/{id}
Requires kpis:read on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
id | integer | yes | The category to return. |
Using curl
curl https://api.simplekpi.com/v1/kpicategories/{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 KPI category
PUT /v1/kpicategories/{id}
A full replacement, not a patch.
Requires kpis:write on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
id | integer | yes | The category to replace. |
Using curl
curl https://api.simplekpi.com/v1/kpicategories/{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 KPI category
DELETE /v1/kpicategories/{id}
The category has to be empty. Move or delete its KPIs first, or the call returns 400.
Requires kpis:write on the API key.
Parameters
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
id | integer | yes | The category to delete. |
Using curl
curl https://api.simplekpi.com/v1/kpicategories/{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 |