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": {}
}

Update 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

​Update 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

Create KPI

Delete KPI

Update 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