Update KPI - Dcycle Platform Docs

Update KPI

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    unit: '<string>',
    value_type: '<string>',
    required: true,
    sort_order: 123,
    options: {}
  })
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/kpis/{kpi_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/kpis/{kpi_id}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "unit": "<string>",
    "value_type": "<string>",
    "required": True,
    "sort_order": 123,
    "options": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/kpis/{kpi_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "unit": "<string>",
  "value_type": "<string>",
  "required": true,
  "sort_order": 123,
  "options": {}
}
'

{
  "id": "<string>",
  "dataset_id": "<string>",
  "name": "<string>",
  "description": {},
  "unit": {},
  "value_type": "<string>",
  "required": true,
  "sort_order": 123,
  "options": {},
  "created_at": {},
  "updated_at": {}
}

PATCH

custom-kpi-datasets

{dataset_id}

kpis

{kpi_id}

Update KPI

const options = {
  method: 'PATCH',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    unit: '<string>',
    value_type: '<string>',
    required: true,
    sort_order: 123,
    options: {}
  })
};

fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/kpis/{kpi_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/kpis/{kpi_id}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "unit": "<string>",
    "value_type": "<string>",
    "required": True,
    "sort_order": 123,
    "options": {}
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

curl --request PATCH \
  --url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/kpis/{kpi_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "unit": "<string>",
  "value_type": "<string>",
  "required": true,
  "sort_order": 123,
  "options": {}
}
'

{
  "id": "<string>",
  "dataset_id": "<string>",
  "name": "<string>",
  "description": {},
  "unit": {},
  "value_type": "<string>",
  "required": true,
  "sort_order": 123,
  "options": {},
  "created_at": {},
  "updated_at": {}
}

← Custom KPI Update one or more fields of a KPI definition. Only send the fields you want to change.

For select KPIs: when you send options, the array replaces the current options entirely. Include existing option ids to keep them (optionally renaming/reordering); omit an id to delete that option. New options (without id) are created.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

string

required

UUID of the parent dataset

string

required

UUID of the KPI to update

Body Parameters

All fields are optional — only send what you want to change.

string

KPI name (1–255 characters)

string

KPI description (max 2000 characters)

string

Measurement unit (max 50 characters)

string

Answer type: number, text, percentage, date, boolean, select

boolean

Whether a response value is mandatory

integer

Display order within the dataset (0-based)

array[object]

For select KPIs: full replacement array of options (2–100). Each object:

Field	Type	Description
`id`	string	Existing option UUID to keep (omit for new options)
`label`	string	Option label (1–255 chars)
`sort_order`	integer	Display order

Response

Returns the updated KPI definition (HTTP 200).

string

KPI UUID.

string

Parent dataset UUID.

string

KPI display name.

string | null

KPI description.

string | null

Measurement unit (e.g. m³, kWh).

string

Data type: number, text, percentage, date, boolean, or select.

boolean

Whether a response value is mandatory.

integer

Display order within the dataset.

array[object]

Available choices for select-type KPIs. Each has id, label, and sort_order.

datetime

Creation timestamp (ISO 8601).

string | null

Last update timestamp (ISO 8601).

Example

curl -X PATCH "https://api.dcycle.io/v1/custom-kpi-datasets/${DATASET_ID}/kpis/${KPI_ID}" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Total electricity consumed (all sources)", "unit": "MWh"}'

import requests
import os

headers = {
    "x-api-key": os.getenv("DCYCLE_API_KEY"),
    "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
    "Content-Type": "application/json",
}

dataset_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
kpi_id = "c3d4e5f6-a7b8-9012-cdef-123456789012"

response = requests.patch(
    f"https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/kpis/{kpi_id}",
    headers=headers,
    json={"name": "Total electricity consumed (all sources)", "unit": "MWh"},
)

kpi = response.json()
print(f"Updated: {kpi['name']} [{kpi['unit']}]")

const axios = require('axios');

const headers = {
  'x-api-key': process.env.DCYCLE_API_KEY,
  'x-organization-id': process.env.DCYCLE_ORG_ID,
  'Content-Type': 'application/json',
};

const datasetId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const kpiId = 'c3d4e5f6-a7b8-9012-cdef-123456789012';

axios.patch(`https://api.dcycle.io/v1/custom-kpi-datasets/${datasetId}/kpis/${kpiId}`, {
  name: 'Total electricity consumed (all sources)',
  unit: 'MWh',
}, { headers })
.then(response => console.log(`Updated: ${response.data.name}`));

Successful Response

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Total electricity consumed (all sources)",
  "description": "Annual electricity consumption across all sources",
  "unit": "MWh",
  "value_type": "number",
  "required": true,
  "sort_order": 0,
  "options": [],
  "created_at": "2025-05-01T09:00:00Z",
  "updated_at": "2025-06-18T15:00:00Z"
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}

403 Forbidden

Cause: The authenticated user is not a member of the organization

{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}

404 Not Found

Cause: KPI not found

{
  "detail": "KPI not found"
}

422 Validation Error

Cause: Empty options array for a select KPI

{
  "detail": [
    {
      "loc": ["body", "options"],
      "msg": "A select KPI needs at least 2 options.",
      "type": "value_error"
    }
  ]
}

Create KPI

Add a new KPI to the dataset

Delete KPI

Remove a KPI definition

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Validation Error

​Related Endpoints

Create KPI

Delete KPI

Request

Headers

Path Parameters

Body Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

Related Endpoints